Skip to content

Latest commit

 

History

History
141 lines (101 loc) · 6.21 KB

CONTRIBUTING.md

File metadata and controls

141 lines (101 loc) · 6.21 KB

Contributing

Cool, that you are interested in contributing. We like pull request and suggestions from everyone.

If you are planning in making a major contribution we appreciate your opening an issue or contacting us.

Things that increase the chance that a pull request will be accepted:

  • Write clean code.
  • Write tests for your new code and regression tests after fixing a bug.
  • Write a good commit message and include the issue number at the end (#123).
  • Update the CHANGELOG.md with any changes/additions made

When merging pull requests we prefer to rebase instead of a squash merge, as this results in a cleaner commit history that makes it easier to detect bugs.

During development on other branches, make sure to always rebase on top of the most current changes on the main branch so that the commits stay in the right order and do not produce as many merge conflicts when closing the pull request. Check the DEV_START_GUIDE.md for more details.

This project is bound by a Code of Conduct.

Naming conventions

Branching

Branch names consist of a type and the describing branch name itself, which is always lowercase separated by dashes. It follows this structure <type>/<issue-id>/<name>. For more detailed information check out the source Branch Types by CKSource

Types Changelog Description
feature yes New feature I add or expand
fix yes Bug fix
docs yes Updated documentation
revert yes Revert of some commit
codestyle no Our beloved code style improvements / refactorings
tech no Other kinds of technical changes

Examples:

  • feature/123/add-settings-option-xyz
  • fix/124/solve-unecpected-settings-errors

Commit Messages

To unify the appearance of all commit messages we only accept commit messages with this structure:

<type>(<scope?>): <subject>(#<issue-number?>)

<body-description?>

Mind the space after the colon!

  • Use the optional body-description to explain what, why or how
  • Separate type/subject-line from optional body-description with a blank line
  • Limit the type/subject line to 72 characters and add the GitHub Issue Number with the # in brackets like this:
    • (#1234)
  • The subject line can be capitalized
  • Do not end the subject line or the body with a full stop
  • <type> can be on of the following:
    • [ 'build', 'chore', 'ci', 'docs', 'feat', 'fix', 'perf', 'refactor', 'revert', 'style', 'test' ]
  • Use an exclamation mark in front of the : to indicate a major breaking change
  • <scope> can be present and contain a list of the following targets:
    • [ 'analysis', 'visualization', 'docker', 'gh-pages', 'docs', 'readme', 'stg', 'config' ]
  • The subject line always uses the imperative mood and is able to complete the following sentence:

    If applied, this commit will ...

Example: chore(visualization): update tree.js dependency to version 0.42 (#1234)

Good <subject> messages

  • ... Add new function to do X (#123)
  • ... Add test for X (#123)
  • ... Refactor subsystem X for readability (#123)
  • ... Update getting started documentation (#123)
  • ... Remove deprecated methods (#123)

Bad messages

  • adding new function to do X for Y #123
  • added service X #123
  • adds tests for X #123
  • fixed bug with Y #123
  • changing behavior of Y #123
  • more fixes for broken stuff #123
  • sweet new API methods #123

Pull Requests

  • Follow the given template when opening the PR
  • Name the PR like its branch name (e.g. Tech/123/my branch name). The name is usually created by GitHub automatically
  • Add the correct labels
  • The PR Assignee is only used by the reviewer to see who is reviewing it

Changelog Guidelines

Principle: https://keepachangelog.com/en/1.1.0/

Why do we write a changelog?

  • A changelog is vital for the developers to keep track of their work. But most importantly now that it appears on every version update to every user, we should make sure that it is also user-friendly. And for that, we need guidelines to help us.

When should you add to the changelog file?

  • You should always make sure that a changelog entry has been added before merging your work.

How should you format a changelog entry?

  • [Description of what you changed] [Link to the pull request] [One picture (specify the width and/or height)]
    Example:
    - Description ([#1315](pull-request-link)) <br>
    ![image-size](image-ling)
  • Please do not forget the _<br> at the end before the img tag (with a space). This breaks the two lines and is compatible with our parsers.

How to write a good description?

  • The description should be precise and short to provide the user with all necessary information. If it is needed, add some precise notes about the usage of the new feature.
  • One changelog entry should describe one change.
  • Avoid writing technical descriptions
  • Start with a verb in the present tense
    • Example: Add, Improve, Enable, Allow, Switch...
    • Don’t: this feature added the ability to enable dark mode
    • Do: Add dark mode
  • Avoid writing ambiguous descriptions
    • Don’t: Fix some UI problems
    • Do: Fix the distribution bar not showing correctly
  • Write in terms of features. Focus on the "what" not the "how".
    • Don’t: Minify JS and CSS
    • Do: Make page load faster by reducing size of JavaScript and CSS files

Notes

  • Link to the image can be copied from an image uploaded to the Pull Request
  • If there are no Pull Requests associated to your change, link an issue.
  • The image should always have a width and/or a height attribute.
    • Example: width=”350px”

Recommended Setup

If you have any questions about the project setup, check out the Dev-Start-Guide!