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