Skip to content

Latest commit

 

History

History
215 lines (167 loc) · 8.39 KB

CONTRIBUTING.md

File metadata and controls

215 lines (167 loc) · 8.39 KB
Raw

Collaborative Development

Impostor Syndrome Disclaimer

Before we get into the details: 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.

We've provided some clear Contribution Guidelines that you can read below. The guidelines outline the process that you'll need to follow to get a patch merged. By making expectations and process explicit, we hope it will make it easier for you to contribute.

And you don't just have to write code. You can help out by writing documentation, tests, or even by giving feedback about this work. (And yes, that includes giving feedback about the contribution guidelines.)

(Adrienne Friend came up with this disclaimer language.)

Prerequisites

Types of interaction

This repository is following the Contributor Covenant Code of Conduct.
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 add your name and details in USERS.cff by using the issue template.

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 develop branch

Load the develop branch:

git checkout develop

Update with the latest version:

git pull
Permanent branches
  • production - includes the current stable version
  • develop - includes all current developments

2.1. Create a new (local) branch

Create a new feature branch:

git checkout -b feature-1314-my-feature

Naming convention for branches: type-issue-nr-short-description

type
  • feature - includes the feature that will be implemented
  • 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.

issue-nr

The issueNumber should be taken from Step 1. Do not use the "#".

short-description

Describe shortly what the branch is about. Avoid long and short 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-42-add-new-ontology-class, feature-911-branch-naming-convention, hotfix-404-update-api, release-v0.10.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

On first commit to the repo:

  • Add your name and details to CITATION.cff

Check branch status:

git status

2.3. Commit your changes

First, make sure you have the pre-commit hooks installed to have your code automatically checked on commit for programmatic and stylistic errors:

pre-commit install

Now, let's add some file. 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: Added function with some method #42 or Update documentation for commit messages #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 --set-upstream origin feature-1314-my-feature

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: develop <- compare: feature-1-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?