How to Contribute

ViRelAy is an open source project and therefore depends on its community. We are always eager to receive contributions and are happy that you found yourself here. If you would like to contribute, there are multiple ways you can help out. You can file bugs or feature request, help to update the documentation, or even contribute code to the project. Before you begin, please read the User Guide section of the documentation to make yourself familiar with the project. In this section we have compiled some helpful tips to get you started. Furthermore, you will find articles on the internals of ViRelAy such as the Database Specification and the Project File Format. ViRelAy consists of 2 parts: the backend REST API written in Python and Flask, and the frontend, which is was created using Angular and Clarity. Please read the articles Backend REST API and Frontend for more information.

Filing Bugs & Feature Requests

If you have found a bug or have a feature request, then the best way to let us know is to open an issue on the project’s GitHub page. Please start by looking through the open issues to find out if someone else has already opened a issue concerning your problem. If so, then please add any information to the issue that might help us resolve it fast. Only open a new issue if there are no other issues concerning the same problem.

When opening an issue, please provide as much information as possible. This will greatly help us identify the issue fast. For example, add some basic system information, such as your operating system and the version of ViRelAy you are using. When filing a bug, please add a detailed step-by-step guide on how to reproduce the bug.

Contributing Code or Documentation

When you want to contribute code to the project, then please first look through all issues to check if there is already an effort to do the same thing that you want to do. If there is no issue concerning the things that you want to add, we would still appreciate if you would open an issue first, where you explain what you want to do. This helps to align your ideas with the rest of the team and may prevent you from doing work, that the team is already planning on doing.

To start contributing, please fork the repository and open a new feature branch with a descriptive name (we use kebab case for branch names, i.e., lower-case words separated by hyphens). Try to make few meaningful coherent commits with expressive commit messages (a short heading followed by a detailed description or a list of changes). Please make sure that after each commit you leave the repository in a functioning condition. If the main branch has progressed since you branched it off, please use a rebase instead of a merge to avoid merge commits.

After contributing to the project, please add yourself to the contributors list (CONTRIBUTORS.md). Don’t forget to update the changelog with the changes you have made (CHANGELOG.md). Also, if necessary, update the documentation. Please comment and document your code extensively. We use a simplified version of the NumPyDoc format for the backend REST API and the JSDoc format for the frontend. Try to emulate the coding style of the project. Please refrain from trying to change the code style. We know that it is tempting to change the code style of a project to your liking, but this will produce unnecessary effort and will only lead to constant style changes. We are using PyLint and Flake8 to enforce the code style and prevent many forms of mistakes in the backend REST API, so please make sure that neither of them produces warnings before committing. Never adapt the PyLint or Flake8 configuration unless you have a really good reason to do so (please tell us about your reasoning in the accompanying issue or the pull request). Most importantly, please write unit tests for all features that you add. We strive to have a test coverage of 100% for the backend REST API (the frontend does not have a test suite, yet). Also make sure that all unit tests pass before committing. Finally, if you have made changes to the frontend, then please build it using the production configuration and put the build artifacts into the virelay/frontend/distribution directory. For more information on all of this, please refer to the Backend REST API and Frontend articles.

PyLint, Flake8, the unit tests, and the documentation build are run as part of our continuous integration (CI) pipeline, which we will run when a pull request is created. Please make sure that the style checks and the unit tests run successfully on your local system using tox before opening a pull request. Pull requests will not be accepted if the CI pipeline does not run successfully. We are currently supporting Python 3.7, 3.8, and 3.9 for the backend REST API and all tests are run for all of these versions, so please make sure that you do not use features that are unavailable in these versions.

When you are finished, you can open a new pull request for your changes and we will review them as soon as possible. Thank you very much for considering to contribute and happy coding!