Skip to content

Latest commit

 

History

History
129 lines (92 loc) · 4.38 KB

CONTRIBUTING.md

File metadata and controls

129 lines (92 loc) · 4.38 KB

Contributing to GWpy

Reporting Issues

When opening an issue to report a problem, please try to provide a minimal code example that reproduces the issue along with details of the operating system and the Python, NumPy, Astropy, and GWpy versions you are using.

Contributing Code

Imposter syndrome disclaimer: We want your help. No, really.

There may be a little voice inside your head that is telling you that you're not ready to be an open source contributor; that your skills aren't nearly good enough to contribute. What could you possibly offer a project like this one?

We assure you - the little voice in your head is wrong. If you can write code at all, you can contribute code to open source. Contributing to open source projects is a fantastic way to advance one's coding skills. Writing perfect code isn't the measure of a good developer (that would disqualify all of us!); it's trying to create something, making mistakes, and learning from those mistakes. That's how we all improve, and we are happy to help others learn.

Being an open source contributor doesn't just mean writing code, either. You can help out by writing documentation, tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process). Some of these contributions may be the most valuable to the project as a whole, because you're coming to the project with fresh eyes, so you can see the errors and assumptions that seasoned contributors have glossed over.

Note: This disclaimer was originally written by Adrienne Lowe for a PyCon talk, and was adapted for GWpy based on its use in the Astropy contributing guide.

Development model

Contributions to GWpy are made via pull requests from GitHub users' forks of the main gwpy repositories, following the GitHub flow workflow. The basic idea is that all changes are proposed using a dedicated feature branch:

  • create the fork (if needed) by clicking Fork in the upper-right corner of https://github.com/gwpy/gwpy/ - this only needs to be done once, ever

  • clone the main repo, calling it upstream in the git configuration:

    git clone https://github.com/gwpy/gwpy.git gwpy --origin upstream
cd gwpy

  • add your fork as the origin remote (replace <username> with your GitHub username):

    git remote add origin [email protected]:<username>/gwpy.git

  • create a new branch on which to work

    git checkout -b my-new-branch

  • make commits to that branch

  • push changes to your remote on github.com

    git push -u origin my-new-branch

  • open a merge request on github.com, this will trigger a code review by one of the GWpy maintainers, who may suggest modifications to your proposed changes

  • to update your feature branch with the latest changes from the main branch of the upstream repository:

    git pull --rebase upstream main

    This rebase will pull in new changes from the upstream/main branch, but will restage your commits on top of the newest upstream changes. This changes the 'history' of your branch, which means you will need to force git to push your changes to github.com:

    git push origin my-new-branch --force

  • finally, if your Pull Request is merged, you should 'delete the source branch' (there's a button), to keep your fork clean

Coding guidelines

Python compatibility

GWpy code must be compatible with Python >= 3.7.

Style

This package follows PEP 8, and all code should adhere to that as far as is reasonable.

The first stage in the automated testing of pull requests is a job that runs the flake8 linter, which checks the style of code in the repo. You can run this locally before committing changes via:

python3 -m flake8

Testing

GWpy has a fairly complete test suite, covering over 90% of the codebase. All code contributions should be accompanied by (unit) tests to be executed with pytest, and should cover all new or modified lines.

You can run the test suite locally from the root of the repository via:

python3 -m pytest gwpy/