1.. _git-workflow:
2
3Git Workflow
4============
5
6Getting new code or changes into Bareos
7---------------------------------------
8All new code should be targeted at our master branch.
9There are no exceptions, so even if you fix a bug in an ancient release, you fix it in master.
10You can then backport your changes to an older release.
11The Git workflow we use is `Github Flow`_.
12
13Basically this means we want you to create pull requests against our master branch.
14We will then build and review the code, request changes as required and eventually merge the pull request.
15You may need to rebase and force-push during the review-phase as master is a moving target.
16
17.. _Github Flow: https://help.github.com/en/articles/github-flow
18
19Releases and Backporting
20------------------------
21The individual releases are tagged with their version number.
22Each major release has its own release-branch.
23Backporting a change into an already release major release is done by applying the change to the major release's branch.
24As with the master branch changes are only accepted as pull requests.
25If you backport a change into a major release, you must make sure it has also been backported into every newer major release.
26So when you backport a change into bareos-17.2, you have to backport it into bareos-18.2 first.
27
28The best practice workflow for this is as follows:
29
30#. `git checkout <major-release-branch>`
31#. `git checkout -b backport-xyz`
32#. Apply your changes using `git cherry-pick -x` or `git am`
33#. `git push -u origin HEAD`
34#. open pull request
35
36Feature Branches
37----------------
38Branches that stage changes like features and bugfixes are considered topic branches and should be short-lived.
39If you merged your topic branch into master (or another release branch while backporting), that branch is then obsolete and should be removed.
40
41Commits
42-------
43A commit should be a wrapper for related changes.
44For example, fixing two different bugs should produce two separate commits.
45Small commits make it easier for other developers to understand the changes and roll them back if something went wrong.
46
47Begin your message with a short summary of your changes (up to 50 characters as a guideline).
48Separate it from the following body by including a blank line.
49
50The body of your message should provide detailed answers to the following questions:
51
52* What was the motivation for the change?
53* How does it differ from the previous implementation?
54
55Commit message guideline
56~~~~~~~~~~~~~~~~~~~~~~~~
57Start with a short (<= 50 characters) summary on a single line, followed by an empty line.
58If your commit changes a specific component of bareos try to mention it at the start of the summary.
59You should write the summary in imperative mood: "Fix bug" and not "Fixed bug" or "Fixes bug."
60
61If your commit fixes or affects an existing bug, add a single line in the format ``Fixes #12345: The exact title of the bug you fix.``, followed by another empty line.
62
63You can now continue with a detailed commit message.
64It should be wrapped at 72 chars and can consist of multiple paragraphs separated by empty lines.
65
66::
67
68  core: sample commit for docs
69
70  Fixes #1234: Documentation requires a sample commit
71
72  This patch adds a sample commit message to the documentation that was
73  previously missing.
74
75  While this does not fix an actual bug, the commit is required so we can
76  show some of the best practices for commit messages. This message
77  applies at least the following practices:
78  - short summary line up to 50 characters
79  - bugfix info for the bugtracker
80  - imperative language
81  - hard limit of 72 characters in the long description
82