Contributingο
Thank you so much for contributing to attune
!
We really appreciate your help.
If you have any questions at all, please either open an issue on GitHub or email a attune
maintainer. The current maintainers can always be found in CONTRIBUTORS.
Preparingο
fork the attune repository (if you have push access to the main repository you can skip this step)
clone
attune
to your machine:$ git clone <your fork>
in the cloned directory (note, to install to system python, you may need to use
sudo
for this command):$ pip install -e .[dev]
run tests
$ pytest
Contributingο
- ensure that the changes you intend to make have corresponding issues on GitHub
if you arenβt sure how to break your ideas into atomic issues, feel free to open a discussion issue
looking for low-hanging fruit? check out the help wanted label for beginner-friendly issues
$ # Create the branch, including remote $ git branch <your branch> --set-upstream-to origin origin/<your branch> $ git switch <your branch> # Switch to the newly created branch
run all tests to ensure that nothing is broken right off the start
$ pytest
make your changes, commiting often
$ git status # See which files you have changed/added $ git diff # See changes since your last commit $ git add <files you wish to commit> $ git commit -m "Description of changes" -m "More detail if needed"
mark your issues as resolved (within your commit message):
$ git commit -m "added crazy colormap (resolves #99)"
If your commit is related to an issue, but does not resolve it, use
addresses #99
in the commit message
if appropriate, add tests that address your changes (if you just fixed a bug, it is strongly reccomended that you add a test so that the bug cannot come back unanounced)
once you are done with your changes, run your code through flake8 and pydocstyle
$ flake8 file.py $ pydocstyle file.py
rerun tests
add yourself to CONTRIBUTORS
push your changes to the remote branch (github)
$ git pull # make sure your branch is up to date $ git push
make a pull request to the master branch
communicate with the maintainers in your pull request, assuming any further work needs to be done
celebrate! π
Styleο
- Internally we use the following abbreviations:
- WrightTools
import WrightTools as wt
- Matplotlib
import matplotlib as mpl
- Pyplot
from matplotlib import pyplot as plt
- NumPy
import numpy as np
attune
follows pep8, with the following modifications:
Maximum line length from 79 characters to 99 characters.
attune
also folows numpy Docstring Convention, which is a set of adjustments to pep257.
attune
additionally ignores one guideline:
attune
does not require all magic methods (e.g.__add__
) to have a docstring.It remains encourged to add a docstring if there is any ambiguity of the meaning.
We use flake8 for automated code style enforcement, and pydocstyle for automated docstring style checking.
$ # These will check the whole directory (recursively)
$ flake8
$ pydocstyle
Consider using black for automated code corrections. Black is an opinionated code formatter for unambiguous standardization.
$ git commit -m "Describe changes"
$ black file.py
$ git diff # review changes
$ git add file.py
$ git commit -m "black style fixes"
We also provide a configuration to use git hooks to automatically apply black
style to edited files.
This hook can be installed using pre-commit
:
$ pre-commit install
When committing, it will automatically apply the style, and prevent the commit from completing if changes are made. If that is the case, simply re-add the changed files and then commit again. This prevents noisy commit logs with changes that are purely style conformity.