Skip to content

Collaborative Development

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

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. If you wish, add your name and details to CITATION.cff.

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

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: - "If applied, this commit will ..." - Follow existing conventions for commit messages - Keep the subject line shorter than 50 characters - Do not commit more than a few changes at the time: atomic commits - Use imperative - Do not end the commit message with a period ~~.~~ - Allways end the commit message with the issueNumber including the "#"

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?