Version Control
===============


Setting up Git
--------------

Initialize Git to use your username and PSI email address, for example::

    git config --global user.name kaminski_k
    git config --global user.email kai.kaminski@psi.ch


Gitlab server
-------------

We use the `PSI-internal Gitlab server <https://git.psi.ch>`_ to host our
repositories.


Groups
------

Currently, all of our repositories are in the repository group ``linux-infra``.

    
Setting up a repository
-----------------------


Repositories containing code are configured along the following lines:

1. Only fast-forward merges are allowed, no merge commits.
2. Merge requests require at least one approval (by someone other than the
   requester).

   
Workflow
--------

Changes to repositories containing **only** documentation can simply be pushed
to the repository in question.

Changes to repositories containing code, SPEC files, or anything else that is
not pure documentation, need to be reviewed - even if the change in question
only changes documentation.

To implement a change, follow these steps:

1. Create an issue on GitLab.
2. Create a feature branch with name starting with
   `issue-n-description`.
3. Assign the issue to yourself when you start working on it.   
4. Commit the change to the feature branch and push it.
5. Create a merge request mentioning the issue in the commit message
   or in the merge request (see `this
   <http://doc.gitlab.com/ee/customization/issue_closing.html>`_ for
   the syntax).
6. Wait for **someone else** to approve and apply the merge request.

   
Commit messages
~~~~~~~~~~~~~~~

A commit message follows the well-known `50/72 format
<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_: 50
characters for the first line of the commit message, followed by a blank line,
which is then followed by zero or more paragraphs with a maximal line-length of
72 characters.

If the commit fixes an issue recorded on Gitlab (which it should), the commit
message must start with ``Fix #N:``, where ``N`` is the number of the issue.
This will automatically close the issue when the commit is merged into master.


Code reviews
~~~~~~~~~~~~

During a code review be sure to check for at least the following:

1. adherence to the guidelines described in this document,e.g. PEP8-compliance
   for Python code
2. solid implementation: edge cases and failures are considered and handled
   appropriately, etc. Non-obvious bits are explained.
3. documentation has been written or changed as appropriate
