Skip to content

Latest commit

 

History

History
194 lines (134 loc) · 7.95 KB

CONTRIBUTING.md

File metadata and controls

194 lines (134 loc) · 7.95 KB

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. Maintain 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 has been inspired by the workflow described by Vincent Driessen.

1. 🐙 Describe the issue on GitHub

Create an GitHub Issue in the repository. Choose a suitable Issue Template for a Feature or a Bug and fill in as much information as possible.
Most important is the Issue Title, it describes the problem you will address.
Update the GitHub Labels and assign to a GitHub Project and Milestone.

▶️ Creating the issue is an important step as it forces one to think about the "issue"!

2. Solve the issue locally

Permanent branches

  • develop - Contains all current developments
  • production - Contains the latest released version
  • gh-pages - Contains the compiled documentation

2.0. 💠 Get the latest version of the develop branch

  • Load the develop branch: 💠git checkout develop
  • Update with online version: 💠git pull

▶️ This should be repeated regularly to avoid parallel 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 new feature that will be implemented
  • enhance - includes enhancements or improvements
  • bug - includes minor fixes and improvements
  • hotfix - includes small improvements before a 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 and enhance 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
  • enhance-911-branch-naming-convention
  • hotfix-404-update-api
  • release-v0.10.0

2.2. 📝 Start editing the files

  • Divide your work into small logical units
  • Start to write the documentation or a docstring
  • Write a unit test that covers the desired outputs and possible errors
  • Don't rush, have the commit messages in mind
  • Add your changes to the 📝CHANGELOG.md
  • Add your name and details to 📝CITATION.cff
  • Check branch status: 💠git status

2.3. 💠 Commit your changes

  • Add a new file: 💠git add filename.md
  • Commit regularly with: 💠git commit filename.md
  • Add REUSE license information

Write a good commit message

Examples of commit message: Add 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.
  • Check branch status: 💠git status
  • Update with online version: 💠git pull
  • If the branch is not on the remote server yet, use: 💠git push --set-upstream origin feature-1314-test
  • Then push with: 💠git push

4. 🐙 Submit a Pull Request (PR)

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 using 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

4.2. 🐙 Delete the feature branch

  • Follow the GitHub guide deleting a branch.
  • Delete the branch (feature, bug, enhance)

5. 🐙 Close the Issue

  • Document the result in a few sentences and close the issue.
  • 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?
  • 🎉 Congratulations dear contributor, let's keep going 🚀

!!! note "Used Icons" 🐙 GitHub | 💠 git | 📝 File | 💻 Command Line