Code review guidelines

Using our purely pull-request-based workflow, code can be developed very flexibly by internal and external contributors. At the same time this workflow allows us to enforce stricter rules on code that ends up in the public repository.

Following are rough guidelines for the code reviewers. These are not meant to prevent progress, but to keep up the code quality as the number of developers is growing. All of this is not set in stone and can be discussed on the NEST mailing lists.

  • In most cases, each pull request needs an OK from the CI platform and at least two reviewers to be merged.

  • The two reviews have to cover the technical side (i.e., if the code does the right thing and is architecturally sound) and the content side (i.e., if the code is scientifically correct and fixes an actual issue).

  • For changes labeled “not code” or “minor” (e.g., changes in documentation, fixes for typos, etc.), the need for a second code review can be waived, and a single review plus the OK from the CI system is sufficient to merge the request.

  • New features like SLI or PyNEST functions, neuron or synapse models need to be accompanied by one or more tests written in either SLI or Python.

  • Each change to the code has to be reflected in the corresponding examples and documentation.

  • A pull request should be coherent and contain only changes that belong together.

  • Please also check that the typesetting of the documentation looks correct. To learn how to test the documentation locally offline, please check out our User documentation workflow.

Before merging, reviewers have to make sure that:

  1. pull request titles match the actual content of the PR and be adequate for the release notes

  1. pull request titles are complete sentences that start with an

upper-case, present-tense verb and end without punctuation

  1. pull requests are assigned to projects and properly and completely labeled

  1. all discussions are settled and all conversations are marked as resolved

  1. there are no blocking issues mentioned in the comments