Here is a simple guideline to get you started with your first contribution.
1. Set up your environment to follow our formatting guidelines and to use signed-commits.
2. Use issues to discuss the suggested changes. Create an issue describing changes if necessary and add labels to ease orientation.
3. Fork super-gradients so you can make local changes and test them.
4. Create a new branch for the issue. The branch naming convention is enforced by the CI/CD so please make sure you are using
hotfix/SG-*** format otherwise it will fail.
5. Implement your changes along with relevant tests for the issue. Please make sure you are covering unit, integration and e2e tests where required.
6. Create a pull request against master branch.
We follow the reStructuredText docstring format (default of PyCharm), along with typing.
def python_function(first_argument: int, second_argument: int) -> str: """Do something with the two arguments. :param first_argument: First argument to the function :param second_argument: Second argument to the function :return: Description of the output """
To ensure everyone uses same code style, a project-wise configuration file has been added to SG repo. It ensures all formatting will be exactly the same regardless of OS, python version or the place where code formatting check is happening.
To start, one need to install required development dependencies (actual versions of black, flake8 and git commit hooks):
$ pip install -r requirements.dev.txt
A pre-commit hook as an easy way to ensure all files in the commit are already formatted accordingly and pass linter checks. If they are not, the git will prevent commit of problematic files unless errors are fixed.
To start, run the following command from SG repo root:
$ pip install pre-commit $ pre-commit install
The command should complete without errors. Once done, all your upcoming commits will be checked via black & flake8.
$ black . from the SG root. It will reformat the whole repo.
$ flake8 --statistics --config scripts/flake8-config setup.py .
Signed commits provide a way to verify the authenticity and integrity of the code changes made by a particular developer, as the commit is cryptographically signed using their private GPG key. This helps ensure that the code changes were made by the intended person and have not been tampered with during transit.
You can find more information here.
Add GPG key to GitHub
- Generate a new GPG key. After completing the steps 1-9 you'll see the console message containing generated key ID (e.g. 3AA5C34371567BD2).
- Copy the GPG key by running the command on step 12 from the link above
$ gpg --armor --export <YOUR_GPG_KEY_ID>
Use GPG key
$ git config --global user.signingkey <YOUR_GPG_KEY_ID> $ git config --global gpg.program $(which gpg) $ git config --global commit.gpgsign true
Making signed commits
-S flag to sign your commit:
git commit -S -m "Making my first signed commit"
You could run the next command to ensure the commit has been signed:
git log --show-signature -1
I have created PR with unsigned commits. Do I have to start over?
No. What you need to do is create another branch starting from master, then move your commits from PR branch to the new branch and force push it to the remote under the old name. Let's say your PR branch named 'feature/my_awesome_pr' then you need to do the following:
git checkout master git checkout -b feature/my_awesome_pr_signed git merge --squash --no-commit feature/my_awesome_pr git commit -S -m "My signed commit" git push -f origin feature/my_awesome_pr_signed:feature/my_awesome_pr
The last command will overwrite your PR branch with the new signed commit containing all changes from the PR.
Some of contributors can face this problem while making their first commit:
error: gpg failed to sign the data fatal: failed to write commit object
GIT_TRACE=1at the beginning of the
git commitcommand, this will show you what the commit command does under the hood. In case you are seeing something like this
18:57:12.099725 run-command.c:663 trace: run_command: /usr/bin/gpg --status-fd=2 -bsau <YOUR_GPG_KEY_ID>
/usr/bin/gpg --status-fd=2 -bsau <YOUR_GPG_KEY_ID>) and execute it separately. Now you can check what happened while running the GPG signature.
Jupyter Notebooks Contribution
Pulling updates from remote might cause merge conflicts with jupyter notebooks. The tool nbdime might solve this. * Installing nbdime
pip install nbdime
nbdiff notebook_1.ipynb notebook_2.ipynb