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

  1. fork the attune repository (if you have push access to the main repository you can skip this step)

  2. clone attune to your machine:

    $ git clone <your fork>
    
  3. in the cloned directory (note, to install to system python, you may need to use sudo for this command):

    $ pip install -e .[dev]
    
  4. run tests

    $ python setup.py test
    

Contributing

  1. ensure that the changes you intend to make have corresponding issues on GitHub
    1. if you aren’t sure how to break your ideas into atomic issues, feel free to open a discussion issue

    2. 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 checkout <your branch> # Switch to the newly created branch
    
  2. run all tests to ensure that nothing is broken right off the start

    $ python setup.py test
    
  3. 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"
    
  4. mark your issues as resolved (within your commit message):

    $ git commit -m "added crazy colormap (resolves #99)"
    
    1. If your commit is related to an issue, but does not resolve it, use addresses #99 in the commit message

  5. 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)

  6. once you are done with your changes, run your code through flake8 and pydocstyle

    $ flake8 file.py
    $ pydocstyle file.py
    
  7. rerun tests

  8. add yourself to CONTRIBUTORS

  9. push your changes to the remote branch (github)

    $ git pull # make sure your branch is up to date
    $ git push
    
  10. make a pull request to the master branch

  11. communicate with the maintainers in your pull request, assuming any further work needs to be done

  12. 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:

  1. 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:

  1. attune does not require all magic methods (e.g. __add__) to have a docstring.

    1. 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.