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:
In all these repositories, we follow the GitHub flow recommondations:
- Create a branch from main.
- Add commits.
- Open a pull request.
- Discuss and review your code.
- Merge into
Create Branch Guidelines
You will work on an own branch to resolve one issue or user story defined on Youtrack. Each of those issues has a DEV-number which has to be used in the branch name:
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 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
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
- 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.
The scope could be anything specifying place of the commit change.
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 Youtrack. 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 PR's with bad titles won't be added to the automatically generated CHANGELOG and release notes. Thus 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 YouTrack 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 contains important informations for its reviewers. Don't copy/paste YouTrack task description here. Instead of that start the description by adding the following:
Github's Autolink Setting will automatically generate a link to Youtrack's 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 label 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
- Rewievers should pay attention to proper PR title setting.
General GitHub actions workflows (CI)
We use GitHub actions to automate some processes.
With each push to GitHub, the tests of the repository are executed. Successfull tests are needed to merge code into repository's main branch (s. Branch protection rules).
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.
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.