Development Process

This page describes all the details about the development process. If you want a short tutorial to start, have a look at Contributing.

Communicating with the Developers

You can communicate with other MONK developers in one of the following ways:

1. The Mailing List: You can ask questions at project-monk@dresearch-fe.de. You can also have a look at the archives to see old conversations.

2. The Bug Tracker: If you have encountered a specific problem you want to work on, you can create an issue here. It is also possible to work via GitHub pull requests.

3. The Stammtisch Meeting: If you happen to be in Berlin on any Tuesday afternoon at 2:30 pm, you are welcome to join our regular meeting on all topics concerning MONK at:

   DResearch Fahrzeugelektronik GmbH

   Otto-Schmirgal-Str. 3

   D-10319 Berlin

   Germany

The Development Process

If you want to see your changes applied to MONK, the best way is to first communicate your ideas with the other MONK developers. You should only start development, if they agree the change makes sense. Otherwise, your work might turn out to be a waste of time.

If you have write access to the repository (which is only supposed to happen if you are a regular member of the DFE group), you should simply fork, create an issue and track your changes in a feature branch.

If you do not have write access, you will have to use pull requests. Remember that a feature branch will automatically be generated for your pull request.

Step-by-step guide:

1. Start from the dev branch: You always need to ensure your commits can be applied without problem on the current HEAD of the dev branch.
2. Create meaningful commits: Commits should adhere to the requirements described in Commit Policy. An important point is, that they should always contain only one meaningful change.
3. Create a pull request: Follow Pull Request Guide on GitHub.
4. Receive acknowledgements: Before a maintainer may accept your changes, you will need to find one or more DFE developers to acknowledge them. These people should be mentioned within your commit message, as described later.
5. Get it merged: If you have a pull request or issue containing your problem, your solution, and the commits containing at least one Acked-By, get one of the maintainers to merge it.

If you need to change anything on your commits, e.g., to add some Acked-by lines, it is okay to rebase -i or commit --amend your changes on your feature branch or pull request as nobody else is supposed to work on the same feature branch anyway.

Branching Model

There are five different kinds of branches in MONK:

1. The Master Branch is the stable branch. It should only contain project states that may be distributed to users.
2. The Dev Branch contains all currently accepted features. Changes here might be more unstable than in the Master Branch and might not be properly documented. Using this branch might sometimes break your code, but as a MONK developer you will always need to start implementing your features and bug fixes from the HEAD of this branch.
3. Feature Branches are used by members of the DFE group to work on new features.
4. Bugfix Branches are used by members of the DFE group to work on bug fixes.
5. Pull Requests are used by external MONK developers who want to get their changes merged into MONK.

Acceptance Criteria For The Dev Branch

dev contains the latest changes that are considered to be working by their creators and at least one reviewer. To continually ensure good quality of the code, some requirements must be met for a commit to be allowed into dev:

• All commits refer to an issue on GitHub.
• The issue contains an understandable description of the problem that enables reproduction, if necessesary.
• The issue contains an understandable and assessable description of the solution.
• All code changes are well documented, formatted according to the coding standards, and follow high quality standards even in areas that are not specifically mentioned here.
• Code changes are unit tested with 100% statement coverage for the changes involved.
• If necessary and possible: integration tests and documentation have been adapted accordingly.
• Two DFE team members have acknowledged the solution’s successful and complete implementation.

These requirements can be overruled only by 100% acceptance of all developers, reviewers, and both maintainers for a single issue, if considered necessary.

Changes to this list of rules can only be achieved by acceptance at the Stammtisch Meeting.

Acceptance Criteria for the Master Branch

The dev branch may be merged into the master branch whenever the Stammtisch decides that MONK‘s current state warrants doing so.

Commit Policy

All commits are are expected to adhere to the following requirements:

• KISS principle: Commits should contain one meaningful change and that one change only. This does not mean you should only put changes in one file or one deletion/insertion into one commit, but that all of the changes should belong together to do one meaningful thing.
• All English: All relevant texts in MONK (like this documentation) are written in English so that non German speakers may use it. This, of course, applies to commits as well.
• Summary Upfront: The first line contains a short summary with no more than 50 characters. This line must be followed by an empty line.
• Descriptive Content: The following paragraphs contain the long description of the problem as well as its solution.
• 72 characters per line: Comment messages should not exceed 72 characters per line, except for longer URLs, quotations or messages that would be unintelligible in some other way when split.
• Refer to an issue on GitHub: If you have not done so already within the description, this would be a good place to specify which issue on GitHub your commit belongs to.
• Signed-off-bys: After the long description all developers involved in creating this commit should be listed on separate lines beginning with Signed-off-by:. These lines should include their names and email addresses.
• Acked-bys: Afterwards all people who checked the quality of the commits should be mentioned in the same fashion with Acked-by: lines.

Finally, a complete example doing everything right:

some_file: limit checks debugged

There was a problem with the limits in this line. They excluded 0,
which is still an acceptable value. This led to unexpected error
messages in the GUI.

The bug was fixed by changing `>0` to `>=0`.

For more details see GitHub issue #312.

Signed-off-by: Peter Parker <parker@dresearch-fe.de>
Acked-by: Bruce Wayne <wayne@dresearch-fe.de>
Acked-by: Clark Kent <kent@dresearch-fe.de>