We love contributions! SkyPy is open source, built on open source, and we'd love to have you hang out in our community. Whether you would like to contribute to SkyPy with your own piece of code or helping develop a concrete feature in SkyPy:
1. Read through our Discussions Page to start a new conversation and share your ideas or follow up an existing conversation on a particular feature.
2. Following the discussions, when you have a good idea of the specifics of the feature you wish to contribute, open an Issue describing the feature.
3. Then follow the Contributor Guidelines on the rest of this page to open a Pull Request to contribute the code implementing the new feature.
SkyPy allows contributions from two types of contributor: Members and External Contributors. These two categories are intended to allow contributions both from those who are willing and able to commit to being part of the SkyPy community and actively involved in the steering of the project, and those who wish to simply contribute code where a need has been identified.
1. SkyPy Members go through a simple onboarding process where their expertise and expected contributions are discussed and defined. Members have access to internal communication channels, they are involved in SkyPy decision making processes and attend quarterly meetings. Members are listed as a separate tier in author lists for SkyPy publications, with the classification of "Creators" in the Zenodo DoI.
2. External Contributors are able to develop, discuss and commit code in the same way as Members, but do not have the same responsibilities and opportunities for contributing to the guidance and management of SkyPy as a project. External Contributors are listed as a separate tier in author lists for SkyPy publications, with the classification of "Others" in the Zenodo DoI.
You should only need to do this step once
First fork the SkyPy repository. A fork is your own remote copy of the repository on GitHub. To create a fork:
- Go to the SkyPy GitHub Repository
- Click the Fork button (in the top-right-hand corner)
- Choose where to create the fork, typically your personal GitHub account
Next clone your fork. Cloning creates a local copy of the repository on your computer to work with. To clone your fork:
git clone https://github.com/<your-account>/skypy.git
Finally add the skypyproject repository as a remote. This will allow you to fetch changes made to the codebase. To add the skypyproject remote:
cd skypy git remote add skypyproject https://github.com/skypyproject/skypy.git
Create a branch off the skypyproject main branch. Working on unique branches for each new feature simplifies the development, review and merge processes by maintining logical separation. To create a feature branch:
git fetch skypyproject git checkout -b <your-branch-name> skypyproject/main
Write the new code you would like to contribute and commit it to the feature branch on your local repository. Ideally commit small units of work often with clear and descriptive commit messages describing the changes you made. To commit changes to a file:
git add file_containing_your_contribution git commit -m 'Your clear and descriptive commit message'
Push the contributions in your feature branch to your remote fork on GitHub:
git push origin <your-branch-name>
Note: The first time you push a feature branch you will probably need to use --set-upstream origin to link to your remote fork:
git push --set-upstream origin <your-branch-name>
When you feel that work on your new feature is complete, you should create a Pull Request. This will propose your work to be merged into the main SkyPy repository.
- Go to SkyPy Pull Requests
- Click the green New pull request button
- Click compare across forks
- Confirm that the base fork is
skypyproject/skypyand the base branch ismain- Confirm the head fork is
<your-account>/skypyand the compare branch is<your-branch-name>- Give your pull request a title and fill out the the template for the description
- Click the green Create pull request button
A series of automated checks will be run on your pull request, some of which will be required to pass before it can be merged into the main codebase:
Tests(Required) runs the unit tests in four predefined environments; latest supported versions, oldest supported versions, macOS latest supported and Windows latest supported. Click "Details" to view the output including any failures.Code Style(Required) runs flake8 to check that your code conforms to the PEP 8 style guidelines. Click "Details" to view any errors.codecovreports the test coverage for your pull request; you should aim for codecov/patch — 100.00%. Click "Details" to view coverage data.docs(Required) builds the docstrings on readthedocs. Click "Details" to view the documentation or the failed build log.
As you work on your feature, new commits might be made to the skypyproject main branch. You will need to update your branch with these new commits before your pull request can be accepted. You can achieve this in a few different ways:
If your pull request has no conflicts, click Update branch
If your pull request has conflicts, click Resolve conflicts, manually resolve the conflicts and click Mark as resolved
merge the
skypyprojectmain branch from the command line:git fetch skypyproject git merge skypyproject/mainrebase your feature branch onto the
skypyprojectmain branch from the command line:git fetch skypyproject git rebase skypyproject/main
Warning: It is bad practice to rebase commits that have already been pushed to a remote such as your fork. Rebasing creates new copies of your commits that can cause the local and remote branches to diverge. git push --force will overwrite the remote branch with your newly rebased local branch. This is strongly discouraged, particularly when working on a shared branch where you could erase a collaborators commits.
- For more information about resolving conflicts see the GitHub guides:
More information regarding the usage of GitHub can be found in the GitHub Guides.
Before your pull request can be merged into the codebase, it will be reviewed by one of the SkyPy developers and required to pass a number of automated checks. Below are a minimum set of guidelines for developers to follow:
- SkyPy is compatible with Python>=3.7 (see setup.cfg). SkyPy does not support backwards compatibility with Python 2.x; six, __future__ and 2to3 should not be used.
- All contributions should follow the PEP8 Style Guide for Python Code. We recommend using flake8 to check your code for PEP8 compliance.
- Importing SkyPy should only depend on having NumPy, SciPy and Astropy installed.
- Code is grouped into submodules based on broad science areas e.g. galaxies. There is also a utils submodule for general utility functions.
- For more information see the Astropy Coding Guidelines.
Pull requests will require existing unit tests to pass before they can be merged. Additionally, new unit tests should be written for all new public methods and functions. Unit tests for each submodule are contained in subdirectories called tests and you can run them locally using pytest. For more information see the Astropy Testing Guidelines.
If your unit tests check the statistical distribution of a random sample, the test outcome itself is a random variable, and the test will fail from time to time. Please mark such tests with the @pytest.mark.flaky decorator, so that they will be automatically tried again on failure. To prevent non-random test failures from being run multiple times, please isolate random statistical tests and deterministic tests in their own test cases.
All public classes, methods and functions require docstrings. You can build documentation locally by installing sphinx-astropy and calling make html in the docs subdirectory. Docstrings should include the following sections:
- Description
- Parameters
- Notes
- References
For more information see the Astropy guide to Writing Documentation.