• Table of contents
• Repository Guidelines
  • Development Workflow
  • Commit Rules

Repository Guidelines¶

The git master repository is available under the following ssh URL:

https://github.com/ecsec/open-ecard.git

The master repository contains the master and stage branch as well as all official tags.
The repository is not writable, except by the integrator.

Every user with git development access has his own repository which is accessible under the following URL:

git@vserver-001.urospace.de:ecard-client/firstname_lastname

To get access to your personal repository, you first have to add it to your remotes. This is accomplished by the following command:

 git remote add local-name-for-repo git@vserver-001.urospace.de:ecard-client/firstname_lastname

local-name-for-repo identifies the remote repository on your local machine. The name can be freely chosen, but it is recommended to use the initials of the developer who owns the repository.

For example, if John Doe wants to add his personal repository to his remotes, he has to execute the following command:

 git remote add jd git@vserver-001.urospace.de:ecard-client/john_doe

The same command can be used to add repositories of other developers.

Development Workflow¶

1. Set local repository to the commit/branch/tag, where you want to write a feature/fix/...
2. Hack
3. If you are working on master or stage, or more general when you have to combine your work with any other change, make sure to update your work properly (do a rebase)
4. If the change is not a Hotfix, it will most likely go into the stage branch.
5. Do a merge request (at the moment at Tobias Wich)
6. Check out tests in CI system
7. Correct change if needed
8. Change goes into master

Commit Rules¶

Commit messages and the appropriate level of granularity is the essence of a readable and comprehensible history. Progit sec. 5.2 recommends that commits are revised with git commit -p or git add -i , before being committed.
If however it becomes apparent that the structure of the commits, or its log messages are badly done, a rewrite of the history with git rebase -i can be used. There are other rewrite tools (magit) which help with the task at hand. http://alexvollmer.com/posts/2009/01/31/rewriting-history-with-git/ has a nice write-up how to rewrite history with the bundled git commands.

Concerning the commit message, there are a lot of descriptions on the web. Most of them are quite similar. One of the more comprehensive descriptions can be found in Progit sec. 5.2 in paragraph Commit Guidelines.

A good commit message begins with a header line which is, according to Progit, 50 characters long. I tend to extend this length to ca. 70 characters. We don't live in times where consoles only have 78 character anymore. The header line should contain a brief summary of the changes in the commit. Issue references should go into the body, because nobody knows what is behind them when looking at the log. An exception to this rule is, when the summary is sufficient to describe the change and no body is needed. The summary must use imperative present tense, meaning 'Add X' instead of 'Added X'. The summary ends without a full stop.
If a body is needed, a blank line followed by the body is inserted after the header line. These items are optional, but it is good practise to add them. The line width of the body should be about 100 characters. The body should contain details and perhaps a motivation for the patch. Especially when adding changes in complicated code, think of cryptography for example, the reader may not understand the change without this explanation. The body may consist of several paragraphs which are separated by blank lines.
Enumerations or bullet points can be used inside the body. They should be indented by one space and their text should be aligned by the first character of the items text. Bullet points should be written with -.

Short (up to 70 chars) summary of changes

More detailed explanatory text, if necessary. Wrap it to about 100 characters or so. In some
contexts, the first line is treated as the subject of an email and the rest of the text as the body.
The blank line separating the summary from the body is critical (unless you omit the body entirely);
tools like rebase can get confused if you run the two together.

Further paragraphs come after blank lines. Enumerations and bullet points look like this:
 - Bullet points are okay, too
 - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank
   lines in between, but conventions vary here
or
 1. Point one
 2. Another point