Skip to content

Latest commit

 

History

History
173 lines (137 loc) · 6.55 KB

CONTRIBUTING.md

File metadata and controls

173 lines (137 loc) · 6.55 KB
Raw

Collaborative Development

Prerequisites

Types of interaction

Please be self-reflective and always maintain a good culture of discussion and active participation.

A. Use

Since the open license allows free use, no notification is required. However, for the authors it is valuable information who uses the software for what purpose. Indicators are Watch, Fork and Starred of the repository. If you are a user, please get in contact with developers via issues or e-mail (as stated in setup.py) and use the Watch function to stay updated.

B. Comment

You can give ideas, hints or report bugs in issues, in PR, at meetings or other channels. This is no development but can be considered a notable contribution.

C. Contribute and Review

You add code and become an author of the repository. You must follow the workflow!

D. Mantain and Release

You contribute and take care of the repository. You review and answer questions. You coordinate and carry out the release.

Workflow

The workflow for contributing to this project has been inspired by the workflow described by Vincent Driessen.

1. Describe the issue on GitHub

Create an issue in the GitHub repository. The issue title describes the problem you will address.
This is an important step as it forces one to think about the "issue". Make a checklist for all needed steps if possible.

2. Solve the issue locally

2.0. Get the latest version of the dev branch

Load the dev branch:

git checkout dev

Update with the latest version:

git pull
Permanent branches
  • master - includes the current stable version
  • dev - includes all current developments

2.1. Create a new (local) branch

Create a new feature branch:

git checkout -b feature/my-feature

Naming convention for branches: type/short-description

type
  • feature - includes the feature that will be implemented
  • fix - includes the quick improvements on the dev branch
  • hotfix - includes small improvements before an release, should be branched from a release branch
  • release - includes the current version to be released

The majority of the development will be done in feature branches.

short-description

Describe shortly what the branch is about. Avoid long descriptive names for branches, 2-4 words are optimal.

Other hints
  • Separate words with - (minus)
  • Avoid using capital letters
  • Do not put your name to the branch name, it's a collaborative project
  • Branch names should be precise and informative

Examples of branch names: feature/add-changelog, fix/docstrings, hotfix/update-plots, release/v1.1.0

2.2. Start editing the files

  • Divide your feature into small logical units
  • Start to write the documentation or a docstring
  • Don't rush, have the commit messages in mind
  • Add your changes to the CHANGELOG.md

Check branch status:

git status

2.3. Commit your changes

If the file does not exist on the remote server yet, use:

git add filename.md

Then commit regularly with:

git commit filename.md

Write a good commit message:

Examples of commit message: Add plotting function #42 or Update documentation #1

2.4 Fix your latest commit message

Do you want to improve your latest commit message?
Is your latest commit not pushed yet?
Edit the commit message of your latest commit:

git commit --amend

3. Push your commits

Push your local branch on the remote server origin.
If your branch does not exist on the remote server yet, use:

git push -u origin feature/my_feature_branch

Then push regularly with:

git push

4. Submit a pull request (PR)

Follow the GitHub guide creating-a-pull-request.
The PR should be directed: base: dev <- compare: feature/collaboration.
Add the line Close #<issue-number> in the description of your PR. When it is merged, it automatically closes the issue.
Assign a reviewer and get in contact.

4.0. Let someone else review your PR

Follow the GitHub guide approving a pull request with required reviews.
Assign one reviewer or a user group and get into contact.

If you are the reviewer:

  • Check the changes in all corresponding files.
  • Checkout the branch and run code.
  • Comment if you would like to change something (Use Request changes)
  • If all tests pass and all changes are good, Approve the PR.
  • Leave a comment and some nice words!

4.1. Merge the PR

Follow the GitHub guide merging a pull request.

4.2. Delete the feature branch

Follow the GitHub guide deleting a branch.

5. Close the issue

Document the result in a few sentences and close the issue.
Check that all steps have been documented:

  • Issue title describes the problem you solved?
  • All commit messages are linked in the issue?
  • The branch was deleted?
  • Entry in CHANGELOG.md?
  • PR is closed?
  • Issue is closed?