Skip to content

How to contribute to the development of the DSP

The DSP software is developed under git version control using GitHub. It includes the following main repositories:

DSP-API DSP-APP DSP-TOOLS DSP-JS-LIB DSP-UI-LIB docs.dasch.swiss

In all these repositories, we follow the GitHub flow recommendations:

  1. Create a branch from main.
  2. Add commits.
  3. Open a pull request.
  4. Discuss and review your code.
  5. Merge into main branch.

Create Branch Guidelines

You will work on an own branch to resolve one issue or user story defined on Jira. Each of those issues has a DEV-number which has to be used in the branch name:

wip/<DEV-nr>-<subject>

The prefix wip stands for "work in progress" followed by a "/" (slash). The second part starts with the DEV-number followed by a short subject which contains a succinct description of the issue/user story. DEV-number and subject have to be written in kebab-case with "-" (hyphens).

Git Commit Guidelines

We follow strict rules how a commit message has to look like. This leads to more readable messages that are easy to follow when looking through the project history and release notes. Since release notes are automatically generated from commits, it is important to follow the Conventional Commit messages.

Commit Message Format

<type>(<scope>): <subject>

Type

Must be one of the following:

  • fix: represents bug fixes, and correlates to a SemVer patch.
  • refactor: represents production code refactoring, and correlates to a patch.
  • feat: represents a new feature, and correlates to a SemVer minor.
  • feat!, fix!, refactor!, etc.: represents a breaking change (indicated by the !) and will result in a SemVer major.\ ⚠ It is important that the exclamation mark is placed before the colon. For example feat!: <subject> or feat(api-v2)!: <subject>
  • docs: documentation changes (no production code change).
  • chore: maintenance tasks (no production code change).
  • style: styles update (no production code change).
  • test: all about tests: adding, refactoring tests (no production code change).

The first four items on this list are taken into account for the release notes and have an effect on the version number.

Scope (optional)

The scope could be anything specifying place of the commit change.

Subject

The subject contains succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize first letter
  • no dot (.) at the end

Pull Request Guidelines

Set title and add description

A pull request usually resolves one issue or user story defined on Jira. Since we started to use the release-please-action it's very important to set the PR title in the correct way, especially because all commits added within the pull request are squashed. Otherwise, PRs with bad titles won't be added to the automatically generated CHANGELOG and release notes. Thus, every PR title has to follow the commit message convention mentioned above, with small modifications.

PR Title Format

<type>(<scope>): <subject> (<DEV-no.>)

It's crucial to start the PR title with the <type> (allowed types), followed by optional<scope> (in brackets and without space between type and scope). <subject> should be Jira task title or its short version. At the end of the PR title add inside the brackets <DEV-no.>, which represents the number of the task(s) related to the PR. Here is an example:

docs(contribution): example pull request title (DEV-001)

The PR description should contain important information for its reviewers. Don't copy/paste the Jira task description here. Instead, start the description by adding the following:

Resolves <DEV-no.>

GitHub's Autolink Setting will automatically generate a link to the Jira issue.

Add a label (optional)

This step is optional, since it has no impact on the release process anymore. However, adding at least one of the corresponding labels to your PR will help quickly realize its purpose:

  • breaking: breaking changes.
  • enhancement: new feature.
  • bug: a bug fix.
  • styling update style (no production code change).
  • documentation: changes to the documentation.
  • testing: all about tests: adding, refactoring tests (no production code change).
  • refactor: refactoring production code.
  • chore: maintenance tasks (no production code change).
  • dependencies: update a dependency package version.

Make a draft

Please convert the pull request to draft as long it isn't ready for reviewing. As soon as the PR is ready for review, click on the corresponding button "Ready for review".

Branch protection rules

The main branch of each repo (it's usually the main branch) is protected by the following rules:

  • Require pull request reviews before merging
    • At least from one reviewer
  • Require status checks to pass before merging
    • Require branches to be up-to-date before merging
    • Status checks e.g. tests defined in each repository's CI

When the PR is merged, the branch will be deleted automatically.

Code Review Guidelines

General GitHub actions workflows (CI)

We use GitHub actions to automate some processes.

Run tests

With each push to GitHub, the tests of the repository are executed. Successful tests are needed to merge code into the repository's main branch (s. Branch protection rules).

Prepare release

We use release-please-action to prepare the next release. This action script automates the CHANGELOG generation, the creation of GitHub releases, and version bumps. In doing so, it creates a release PR which updates itself with each push into main branch following the commit messages. It's important to use the defined rules from above in all commits and in PR titles.

Create release

When we are ready to tag a release, simply merge the release PR. This will create a release on GitHub, builds the npm package or the docker image and publishes on the corresponding platform.

DSP-API Docker Image DSP-JS NPM Package DSP-UI NPM Package DSP-APP Docker Image

Last update: June 7, 2023