Contributing

Thank you for considering contributing to nx3d.

This project is free and open source, so the best way to contribute is by writing code.

This page describes the development cycle you may follow - it should be familiar to most developers.

1. Pick an issue

Navigate to the issue tracker and look for “good beginner issues”. Or if you have a bee in your bonnet about something, please feel free to go off king/queen/royal.

2. Clone the code

cd ~/path/to-your/projects/
git clone git@github.com:ekalosak/nx3d.git

3. Setup the development environment

You can do this as you like, though you might consider using pyenv and poetry for replicable virtual environments and package management:

  1. Install pyenv and pyenv-virtualenv for managing virtual environments.

  2. Run pyenv install 3.10.7 or whichever supported version of Python.

  3. Run pyenv virtualenv 3.10.7 nx3d3107 to create the virtual environment.

  4. Run pyenv activate nx3d3107 to activate the virtual environment. python --version should be correct.

  5. Install poetry for managing dependencies and virtual environments.

  6. Run poetry shell to open a clean shell. which python should be a poetry shim.

  7. Run poetry install to install the project, dependencies, and developer dependencies.

  8. Run poetry install . -e to install a development copy of nx3d.

Verify the setup by running python -m nx3d. You should see a popup appear with a neat little graph widget you can spin around and zoom in on.

If you need to update project dependencies, note that that you will need to use poetry.

4. Solve the issue you picked

Ok now write code. Use pytest to make sure core functionality hasn’t broken. Run python -m nx3d diffusion to confirm integration works.

5. Set up pre-commit

The pre-commit hooks defined in .pre-commit-config.yaml apply linting and formatting to keep the project clean. Please use the pre-commit hooks before opening a PR.

First time setup

From this project’s root, initialize pre-commit as follows:

pre-commit install
pre-commit run -a

6. Update the docs

  1. Update the inline docstrings and/or the files in the docs/ directory.

  2. Navigate to the docs/ dir and run make html to preview your changes.

  3. When you cut a PR, the CI will trigger a ReadTheDocs build.

  4. When merged, the CD will publish those docs (3).

First time updating the docs

I used brew install python-sphinx, see installation instructions on www.sphinx-doc.org.

7. Open a PR

Increment the version in the pyproject.toml and docs/conf.py files. When a PR is created or updated, code checks will be run and documentation preview will be generated. When a PR is merged, the code will be pushed to PyPi and the docs to ReadTheDocs.