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

    $ pytest
    

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

    $ pytest
    
  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.