Thank you for your interest in contributing to NeuroML. Welcome!
This page documents the contribution guidelines for all NeuroML related repositories.
Please do remember that these are guidelines but not rules that must be strictly followed. We think these are reasonable ideas to follow and they help us maintain a high code quality while making it easier and more efficient for all of us to work together. However, there may be cases where they can not be followed, and that’s fine too.
Code of conduct¶
All NeuroML projects are governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behaviour to the moderators of the communication channel you are in.
Structure of repositories¶
All NeuroML repositories use the Git version control system.
Contributions are made using pull requests.
Each NeuroML software tool resides in its own GitHub repository under the NeuroML GitHub Organization, apart from libNeuroML which is developed in collaboration with the NeuralEnsemble community and so lives under their GitHub organization.
LEMS repositories are housed under the LEMS GitHub Organization.
You can find links to these on the respective pages for each software tool.
The NeuroML standard itself (schema and ComponentType definitions) is housed in its own repository here.
All NeuroML repositories (including the standard) follow Semantic versioning.
This means that the version string consists of three components:
the MAJOR version is incremented when incompatible API changes are made,
the MINOR version is incremented when functionality is added in a backwards compatible manner, and
the PATCH version is incremented when backwards compatible bug fixes are made.
Please develop against the
developmentbranch in all repositories. This branch is merged into
mastervia a pull request when a new release is made. This ensures that all tests are run at each step to verify correctness. As a result, the
masterbranch of all repositories holds the stable version of the standard and tools, while the
developmentbranch holds the next, unstable version that is being worked upon.
For branch names, please consider using the Git flow naming convention (not mandatory but strongly suggested):
prefix feature branches with
prefix bugfix branches with
pull requests addressing specific tickets may also mention them in the branch name. E.g.,
Git commit messages are extremely important because they allow us to nicely track the complete development history of the project. Here are some guidelines on writing good commit messages:
Each commit should ideally only address one issue. It should be self-contained (should not group together lots of changes). Tip: use
git add -pto break your work down into logical, small commits).
Write good commit messages. Read this post to see how to write meaningful, useful commit messages and why they are important.
We strongly suggest using the Conventional Commit specification. In short:
Each commit is of the form
<type>[optional scope]: description, followed by the text body of the commit after a blank line, and then any optional references etc. as footer.
typecan be one of:
test, and so on depending on what the commit is doing.
Any backwards incompatible, breaking change must be clearly noted in the commit using the
BREAKING CHANGEphrase. This corresponds to a major version update (as noted above in the versioning section).
Code style: Java¶
Code style: Python¶
While Python 2 is still supported even though it is no longer supported by the Python community, given that most Python modules (numpy/scipy/matplotlib/sphinx) have dropped support for this deprecated Python version, NeuroML will also drop support in the near future. Therefore, we strongly suggest using Python 3.
For Python repositories, please use Black to format your code before committing and submitting a pull request.
We also strongly suggest linting using flake8.
Please use type hints in your code and run mypy to test it for correctness. You can see the mypy cheatsheet to quickly see how to do this. Since NeuroML is currently still supporting Python 2, we use the Python 2 style to maintain compatibility (this also works with Python 3).
All tools include their own documentation in their repositories. Please feel free to improve this documentation and submit pull requests.
When contributing fixes and enhancements, please remember to document your classes/functions and code in general. Not only does this allow others to understand your code, it also allows us to auto-generate documentation using various tools.
For the Java repositories, please use the standard Javadoc syntax.
Where applicable, please add examples and so on to the software documentation to ensure that users can find the information quickly. Additionally, please remember to consider if this primary NeuroML documentation here needs to be updated.
Please use Semantic Line Breaks wherever possible.
Before submitting a pull request, please run the various tests to confirm your changes. You can see how they are run in the various GitHub workflow files (in the
.github/workflows/folder in each repository). They will be run on all pull requests automatically so you can also verify your changes there.
For a new feature addition, please remember to include a unit test.
For a bug fix, please include a regression test.