Skip to content

Latest commit

 

History

History
162 lines (132 loc) · 5.29 KB

CONTRIBUTING.md

File metadata and controls

162 lines (132 loc) · 5.29 KB
Raw

Contributing to typhon

Thank you for considering to contribute to the typhon project! 🎉 👍

As a community-driven project we rely on the work and contribution of volunteers. By participating in this project, you agree to abide by the code of conduct.

In order to contribute to typhon you need to be registered on GitHub.

Checklist

This checklist is closely based on a blog post by Davide Coppola. It also serves as a table of contents.

  1. Fork the project
  2. Clone your fork
  3. Set up your fork
  4. Update your fork
  5. Create a branch
  6. Work on your contribution
  7. Pull request
  8. Code review
  9. Follow up

General information on how to setup a development environment using Anaconda can be found on the bottom of this page

Fork the project

The first step is to fork the typhon project. This is done by clicking the Fork button on the project site.

Clone the forked project

After forking the project you can clone the project to create a local working copy.

$ git clone https://github.com/YOUR_USERNAME/typhon.git

You can also connect to GitHub using SSH.

Set up cloned fork

Add the URL of the original project to your local repository to be able to pull changes from it:

$ git remote add upstream https://github.com/atmtools/typhon.git

Listing the remote repositories will show something like:

$ git remote -v
origin https://github.com/YOUR_USERNAME/typhon.git (fetch)
origin https://github.com/YOUR_USERNAME/typhon.git (push)
upstream https://github.com/atmtools/typhon.git (fetch)
upstream https://github.com/atmtools/typhon.git (push)

Update your fork

Make sure to pull in changes from the upstream master branch at regular intervals to keep track of changes done to the project. We recommend to use the --rebase flag. This will replay your commits on top of the latest typhon git master and maintain a linear history.

$ git pull --rebase upstream master

Create a branch

Before starting to work on your feature or bugfix you need to create a local branch where to keep all your work. Branches help to organize the changes related to different developments in the project.

You can do that with the following git command:

$ git checkout -b BRANCH_NAME

This will create a new branch and will make it the active one in your local repository. Be sure to use a descriptive name for the branch name.

You can check you are in the right branch using git:

$ git branch
  master
* BRANCH_NAME

The current active branch is the one with a * on the left.

Work on your contribution

Now you can start with the development of your new feature (or bug fix). We recommend to do this in a separate Anaconda environment. See the instructions further down on how to set this up.

During the work you can use git's commit and push mechanism to save and track your changes.

You can push those changes to your personal fork.

$ git push origin BRANCH_NAME

Pull request

After pushing your changes to your fork navigate to the GitHub page of your work. Click on the Pull request button. Add the needed information to the web form and submit your request.

Code review

The developer team will review your changes and decide whether to accept your changes. This process might include some discussion or even further changes to the code (this is the reason why branches are important).

Follow up

After your contribution has been merged to the main project (or rejected) you can delete the branch you used for it.

To delete the branch in your local repository and on GitHub:

$ git branch -D BRANCH_NAME
$ git push origin --delete BRANCH_NAME

Anaconda development environment

We strongly recommend to use Anaconda for your Python development. Follow the instructions on the linked page to set up a working Anaconda system.

Afterwards, you have to create a local working copy of the typhon repository:

$ git clone https://github.com/atmtools/typhon.git  # or your own fork
$ cd typhon

Now you can use conda to install required dependencies and libraries:

$ conda config --add channels conda-forge
$ conda install --file requirements.txt

Finally, pip can be used to install the cloned working copy to your Python environment (make sure to use the pip installed with conda and not the system version.)

$ pip install --no-deps --user --editable .

This will install the package in editable mode (develop mode) in the user's home directory. That way, local changes to the package are directly available in the current environment.

With all the dependencies available you can now run the checks

pytest

and also build the documentation in the doc/ subdirectory:

cd doc
make clean html

The documentation is now available as HTML files in _build/html/.