Skip to content
This repository has been archived by the owner on Oct 19, 2022. It is now read-only.

How to contribute

Jump to bottom
Daniel edited this page Jun 5, 2020 · 17 revisions

General information

If you plan to contribute to the project, first a big thank you 🥇. To be able to handle Pull requests (PRs) and other contributions, please adhere to the following rules and hints:

Table of Contents

Issues

  • Please perform a basic search if a similar issue already exists. If this is the case please add additional information to the already existing issue, instead of creating a new one
  • Every issue should follow the given templates
  • Don't hesitate to create new issues, regardless if it is a feature or a bug
  • If technical implementation details are known at the time of issue creation those should be added
  • Code changes should not exceed the requested scope. If additional changes are planned those must be approved and noted down in the comments. So everyone can follow the development flow

Additional internal steps and flows for Open Xchange employees.

Pull requests

Pull requests are the way to go to contribute to this project. PRs should always be related to an issue.

Create a pull request

To contribute perform the following steps:

  • Fork the repository on GitHub if required
  • Clone the repository if required
  • Implement your changes on a feature branch
    • A PR should not exceed the scope given by the issue
    • Rebase your changes onto the latest develop and check if everything is still working as expected
  • Create a pull request for the feature branch
    • Verify the PR contains the changes you intended to push and only those (remove auto generated files, debug code and similar stuff)
  • Add all required information, requested by the template
    • Add the corresponding GitHub issue (if given) and prefix Fixes (e.g. Fixes #1337), so GitHub automatically handles the ticket for us, if the PR is merged
    • Add a description of important implementation steps, to allow the reviewer to understand the idea behind the changes
    • Add a description of additional changes, to allow the reviewer to differentiate between the actual implementation of an issue and e.g. additional clean ups
  • Assign a reviewer if it's known who should review a ticket, otherwise leave the field empty
  • Verify all checks went green after creating the PR, otherwise please fix remaining problems

Review a pull request (PR)

  • Check if all checks are green, if not request adjustments from the PR creator
  • Checkout the given branch
  • Check the functionality
  • Review the code and add remarks if required
    • If changes are applied and the PR is updated, start the process from the beginning
  • As soon as functionality and code are ready use the Squash and merge button to apply the changes
  • Use the Delete branch button to remove the feature branch after merging
  • Close related issues on GitHub and if existing in the internal bug tracker (the latter is only relevant for employees of Open-Xchange)

Git

Branch names

The general rule is that only GitHub related branches (so branches that have an issue on GitHub) should be in the root branch level of the project. Everything else should be located in a sub folder / sub area of the project. Exceptions are develop and master.

Please use the following naming scheme for branches:

  • develop - Branch for continuous development (no direct pushes allowed)
  • master - Stable branch for releases (no direct pushes allowed)
  • ###_xxYyZz - Feature branches (### = issue number, xxYyZz = short camel case description of the issue)
    • For example: 256_addedLoginTests
  • app/###_xxYyZz - Feature branches in the plugin repository, which are only created because of an issue in the app (if no issue for the plugin exist, ### = issue number in the app repository, xxYyZz = short camel case description of the issue)
    • For example: app/256_addedLoginTests
  • plugin/###_xxYyZz - Feature branches in the app repository, which are only created because on an issue in the plugin (if no issue for the app exists, ### = issue number in the plugin repository, xxYyZz = short camel case description of the issue)
    • For example: plugin/256_addedLoginTests
  • Special cases:
    • release/xxYyZz - Release branches - For example: release/beta-1337
    • hotfix/xxYyZz - Hotfix branches (if no ticket exists) - For example: hotfix/appCrashesOnMondays
    • build/xxYyZz - Build / tools related branches (if no ticket exists) - For example: build/fixCi
    • cleanup/xxYyZz - Clean up / refactoring related branches (if no ticket exists) - For example: cleanup/fixNaming
    • documentation/xxYyZz - Documentation related branches (if no ticket exists) - For example: documentation/updateHowToContribute

Open Xchange employees please be aware of this special case:

  • OT/###_xxYyZz - Feature branches with no issue in one of the GitHub repositories, but only a Jira issue number (### = issue number in Jira)
    • For example: OT/256_addedLoginTests

Commit messages

Please use one of the following prefixes / suffixes for commit messages:

  • Xx Yy Zz #123 - For ticket implementation (123 = GitHub ticket number)
    • For example: Added login tests #256
  • Xx Yy Zz PROJECT/123 - For ticket implementation, if the ticket exists in a different GitHub repository / project (PROJECT = name of the other GitHub repository, 123 = GitHub ticket number)
    • For example: Added login tests flutter-deltachat-core/256
  • If no ticket exists (shouldn't be the case normally)
    • CLEANUP - For smaller ad hoc adjustments - For example: CLEANUP Wrong naming
    • BUILD - For build related issues - For example: BUILD Fix ci
    • HOTFIX - For important bug fixes - For example: HOTFIX Crash on mondays
    • DOCU - For documentation fixes - For example: DOCU Fix typos

If a commit handles multiple tickets please add a reference to all tickets.

Open Xchange employees please be aware of this special case:

  • OT-### Xx Yy Zz - Every commit related to a Jira issue must reference the Jira issue (### = issue number in Jira)
    • For example (if only a Jira issue exists): OT-256 Added login tests
    • For example (if Jira and GitHub issues are given): OT-256 Added login tests #1337

Examples

This area contains some examples, which could help in some cases. Feel free to apply your own Git workflow, those examples should just be a help.

Rebase your changes onto develop

To reduce work we recommend to squash your commits prior the rebase onto develop. To rebase your changes update your develop and apply your changes on top. Verify no uncommitted changes are in your workspace. Replace $branchName with your branch.

git checkout develop
git pull
git checkout $branchName
git rebase develop

If merge problems occur fix them before creating a pull request.

Squash everything into one commit

Verify no uncommitted changes are in your workspace. Replace $branchName with your branch and $commitCount with the amount of commits which should get squashed into one. If you have added 4 commits, the count would be 4.

git checkout $branchName
git rebase -i HEAD~$commitCount

Replace pick for all commits which should get squashed with s. Most of the time you will keep pick for the first commit and use s for all other commits.

pick 8ec3b1f OT-454 Autocrypt setup is not sorted correctly into chat list
s 1a251af clean up
s 833f323 fix broken tests
s e9ed6e6 hotfix

Save the file and edit the commit message in the next step. Just keep one commit message, which is relevant and describes which ticket you just tackled. See How-to-contribute: Commit-messages for further information around the commit message.

Clone this wiki locally