This page documents how Git and GitLab is used. It is strongly recommended that you read A successful Git branching model by Vincent Driessen. His article explains the use of git branches to organize work. In particular, the master branch is used for major releases, the develop branch for development and feature branches for every new feature. The most important bits are reproduced here to match our case.
Note that these guidelines are intended for kernel development. Things are not
as strict for other repositories (those in usr
or bin
), however it is
highly recommended to follow these guidelines whenever you can as a means of
organizing work.
Creating an issue
Once you get an idea, the first step is to create an issue at GitLab. Issues let you track the work you do on a feature, including the management of branches, changes, time estimates etc.
First, point your web-browser to the GitLab repository. On the left, click on Issues and create a new issue. Create a meaningful title and describe the work you are going to do. You do not need to write a detailed description, it is mostly to remember what the issue is about both now and in the future. If you look at the right, you will find tools for time tracking as well as managing milestones and responsibilities.
Creating the feature branch
Now that you have created an issue, it is time to create the work branch. When you want to develop a new feature, you are required to do so on a separate feature branch. You may create as many commits as you want on this new branch. To create a branch that is automatically linked to the issue, press the "Create merge request" button on the issue page. This will create both a new branch and a merge request that will be used when the work is done.
In order to get to the new branch:
git pull
git checkout myfeature
When you have made all your commits, push it to GitLab:
git push
A word on commit-messages
It is preferable that you write your commit-messages as a descriptive but short sentence. Start with a capital letter and end with a dot. For example, the commit adding the first contents of this page has the commit message "Write about how we use git and gitlab.".
Requirements
Before you proceed you must check that the additions meet a few requirements:
- New features are properly documented and changes are reflected in the documentation. Code has to be documented in code and in the markdown documents that are to appear on this site. Have a look at "Documenting Your Code" for details.
- The proper code standards are followed. This is detailed at the "Code Standards" page.
- Common sense is used. Keep things clean and in the appropriate directories.
- There should not be any dead code (commented out blocks). Remember that old code will still be in the Git history.
- The code must compile.
- The changes must not break something unintentionally. Certain changes are supposed to affect outside code, these are of course allowed. Remember to test your code.
Submitting a merge request
Once you are satisfied with your work and are confident that it works properly, submit a merge request using GitLab. If you used the button at the issue page this merge request is already created. All you have to do is open it and press "Resolve WIP status" when you are done with your work. It is now time to wake someone else that will help checking that the code is good, properly documented etc. Eventually, the maintainer for the develop branch will merge it into develop and delete the work branch to keep the repository clean. Do not worry, it does not delete your work, it will still be visible in the repository and the commit graph. What it does is prevent clutter in the list of branches. When the work is accepted, you may then switch back to the develop branch locally and check:
git checkout develop
git pull
In case you messed up with the entire issue, branch and merge request thing, you can still create a merge request from an arbitrary branch. Go to the GitLab page for the repository, navigate to "Merge Requests" and create a new request. Make shure you select your branch and the develop branch, then continue. On the new page, write a title for the request and a sentence or two in the description, so that the maintainer knows what you made.
Right above the "Submit merge request" button make shure you have checked "Remove source branch when merge request is accepted". Later on, you may continue work by creating a new branch with the same name even.
After your code has been merged
If the repository is set up with GitLab CI/CD, your changes will automatically be tested and a green checkmark will appear next to the merge commit if the tests succeeded. If you made any changes to the documentation (you probably did since the request was accepted), you may view the changes at the related documentation web-pages.
When the time comes and a new release of the entire project is due, the develop branch will be merged into master. Only then will your changes appear in the master branch and in any official releases.
Potential troubles
While you are developing your feature, others are likely to submit code to the develop branch. In order to keep yourself up to date, have a look at this GitHub page.