Skip to content

Latest commit

 

History

History
139 lines (75 loc) · 4.57 KB

CONTRIBUTING.md

File metadata and controls

139 lines (75 loc) · 4.57 KB
Raw

Contributing

Please open issues to discuss enhancements and bugs that you may encounter with pyNeuroML. Pull requests with enhancements and bug fixes are welcome.

Virtual environments and editable installs

It is best to use virtual environments when developing Python packages. This ensures that one uses a clean environment that includes the necessary dependencies and does not affect the overall system installation.

For quick development, consider using editable installs.

PyNeuroML includes a number of scripts that provide the various command line tools. When making changes to the code, one must re-install the package to ensure that these command line tools are up to date:

pip install -e .   # for an editable install

The dependencies are broken down in the setup.cfg file. To get a complete development environment, one can run:

pip install -e .[dev]   # an editable install with all development dependecies installed

Code style

  1. The source code uses spaces, and each tab is equivalent to 4 spaces.

  2. We use the reStructuredText (reST) format for Python docstrings. Please document your code when opening pull requests. All methods/functions/modules must include docstrings that explain the parameters.

  3. We use ruff to format and lint our code. (See the section on pre-commit below.)

  4. Please use type hints wherever applicable. You can set up type checkers such as mypy to use type hints in your development environment/IDE.

     pip install mypy

Pre-commit

A number of pre-commit hooks are used to improve code-quality. Please run the following code to set up the pre-commit hooks:

$ pre-commit install

The hooks will be run at each git commit. Please see .pre-commit-config.yaml for information on what hooks we run.

Commit messages

Writing good commit messages makes things easy to follow. Please see these posts:

Tests

Bug fixes and new features should include unit tests to test for correctness. One can base new tests off the current ones included in the tests/ directory. To see how tests are run, please see the GitHub Actions configuration file.

We use pytest for unit testing. One can run it from the root of the repository:

pytest

To run specific tests, one can use the -k flag:

pytest -k "..."

Pull Request Process

  1. Please contribute pull requests against the development branch.
  2. Please ensure that the automated build for your pull request passes.
  3. Please write good commit messages (see the section above).

Updating your pull request branch

Over time, as pull requests are reviewed, the development branch continues to move on with other changes. Sometimes, it can be useful/necessary to pull in these changes to the pull request branch, using the following steps.

Add the upstream pyNeuroML repository as a remote:

git remote add upstream https://github.com/NeuroML/pyNeuroML.git

Update your local copy of the development branch, and the remote copy in your fork:

git checkout development
git pull upstream development
git push

Pull in changes from development to your branch:

git checkout <feature branch being used for PR>
git merge development

If there are merge conflicts, you will need to resolve these, since merging the feature branch in the pull request will also result in these. After any merge conflicts have been resolved (or if there aren't any), you can push your branch to your fork to update the pull request:

git push

Man pages

We auto-generate man pages for all the command line tools using help2man. To regenerate these:

pip install -e . # ensure latest version of package tools are installed
cd man/man1/
./generate-man-pages.sh

One can preview the man pages:

man -l <path to man page file>

If all looks well, check in the man pages and commit:

git add .