Contributing
Working from a Fork#
If you want to contribute to the development of Salt, you should work from a fork of the repository. You can read about forking workflows here, or take a look at the contributing guidelines in the training dataset dumper documentation.
After creating a fork, clone the fork and add the upstream repository.
git clone ssh://git@gitlab.cern.ch:7999/<cern_username>/salt.git
git remote add upstream ssh://git@gitlab.cern.ch:7999/atlas-flavor-tagging-tools/algorithms/salt.git
Ensure your fork is not set to private
This prevents the results of the CI from being visible in MRs to the main repo.
You should make changes inside a feature branch in your fork. It is generally a good idea not to work directly on the the main branch in your fork. Then, when your feature is ready, open a merge request to the target branch on upstream (which will usually be main). Once this is merged to upstream, you can git pull upstream main from your fork to bring back in the changes, and then fork again off main to start the development of a new feature. If your feature branch becomes outdated with its target, you may have to rebase or merge in the changes from the target branch, and resolve any conflicts, before you can merge.
Remember to keep you fork up to date with upstream.
Contribution Workflow#
When adding features or fixing bugs, it's a good idea to let people know what you plan to work on before you start working on it. The following procedure should be followed:
- (Optional) Informal discussion on mattermost to check if the feature/bug exists, and is a suitable addition.
- Open an issue on GitLab. This is a place to describe in more detail the feature/bug, and to work out what is necessary to change in the code.
- Assign a responsible person to the issue. If the person who opened the issue has they capability, by default they should assign themselves to the issue. Otherwise the maintainers will assign a responsible person.
- Merge request. The assigned person should work on the feature and open a MR. This will be reviewed, any follow-up issues created, and finally merged. The corresponding issue should be closed.
Code Standards#
Good coding standards are highly encouraged. You can take a look at the umami docs or the coding style tutorial for guidance on code style. In short, aim to write clean, readible and type-hinted code with module and function docstrings, and plenty of inline comments. Code is formatted using black (this is enforced by the pre-commit checks).
VS Code is the recommended editor when developing for salt.
The package comes with some recommended extensions which you can review and install by running the Extensions: Show Recommended Extensions command.
See also the umami guide for development with VS Code.
Pre-commit Checks#
The pre-commit framework is used to ensure contributions follow good coding standards.
It is installed as a package dependency.
To set it up, just run the following from the top level of the package.
pre-commit install
The pre-commit checks will then be run every time you run git commit.
You can run them manually over staged changes using
pre-commit run
Include the --all-files flag if you want to run the checks over all the files in the repository.
Test Suite#
From the salt/ source directory (the one with the tests/ dir inside), run
pytest --cov=salt --show-capture=stdout
Adding --show-capture=stdout just hides a bunch of DEBUG statements.
Getting help#
If you need help, you can ask on mattermost or open an issue in the repository.
Created: October 7, 2022