diff options
Diffstat (limited to 'doc/topics/gitlab_flow.md')
| -rw-r--r-- | doc/topics/gitlab_flow.md | 81 |
1 files changed, 41 insertions, 40 deletions
diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index c238951be51..df5029bb0d1 100644 --- a/doc/topics/gitlab_flow.md +++ b/doc/topics/gitlab_flow.md @@ -45,13 +45,13 @@ For a video introduction of how this works in GitLab, see [GitLab Flow](https:// <!-- vale gitlab.Spelling = YES --> Git flow was one of the first proposals to use Git branches, and it has received a lot of attention. -It suggests a `master` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes. -The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `master` branch. +It suggests a `main` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes. +The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `main` branch. Git flow is a well-defined standard, but its complexity introduces two problems. -The first problem is that developers must use the `develop` branch and not `master`. `master` is reserved for code that is released to production. -It is a convention to call your default branch `master` and to mostly branch from and merge to this. -Because most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch. +The first problem is that developers must use the `develop` branch and not `main`. `main` is reserved for code that is released to production. +It is a convention to call your default branch `main` and to mostly branch from and merge to this. +Because most tools automatically use the `main` branch as the default, it is annoying to have to switch to another branch. The second problem of Git flow is the complexity introduced by the hotfix and release branches. These branches can be a good idea for some organizations but are overkill for the vast majority of them. @@ -59,7 +59,7 @@ Nowadays, most organizations practice continuous delivery, which means that your Continuous delivery removes the need for hotfix and release branches, including all the ceremony they introduce. An example of this ceremony is the merging back of release branches. Though specialized tools do exist to solve this, they require documentation and add complexity. -Frequently, developers make mistakes such as merging changes only into `master` and not into the `develop` branch. +Frequently, developers make mistakes such as merging changes only into `main` and not into the `develop` branch. The reason for these errors is that Git flow is too complicated for most use cases. For example, many projects do releases but don't need to do hotfixes. @@ -68,10 +68,10 @@ For example, many projects do releases but don't need to do hotfixes.  In reaction to Git flow, GitHub created a simpler alternative. -[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `master` branch. +[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `main` branch. This flow is clean and straightforward, and many organizations have adopted it with great success. Atlassian recommends [a similar strategy](https://www.atlassian.com/blog/git/simple-git-workflow-is-simple), although they rebase feature branches. -Merging everything into the `master` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices. +Merging everything into the `main` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices. However, this flow still leaves a lot of questions unanswered regarding deployments, environments, releases, and integrations with issues. With GitLab flow, we offer additional guidance for these questions. @@ -88,7 +88,7 @@ While this is possible in some cases, such as SaaS applications, there are some operations team is at full capacity - but you also merge code at other times. In these cases, you can make a production branch that reflects the deployed code. -You can deploy a new version by merging `master` into the production branch. +You can deploy a new version by merging `main` into the production branch. If you need to know what code is in production, you can check out the production branch to see. The approximate time of deployment is visible as the merge commit in the version control system. This time is pretty accurate if you automatically deploy your production branch. @@ -99,16 +99,16 @@ This flow prevents the overhead of releasing, tagging, and merging that happens  -It might be a good idea to have an environment that is automatically updated to the `master` branch. +It might be a good idea to have an environment that is automatically updated to the `main` branch. Only, in this case, the name of this environment might differ from the branch name. Suppose you have a staging environment, a pre-production environment, and a production environment. -In this case, deploy the `master` branch to staging. -To deploy to pre-production, create a merge request from the `master` branch to the pre-production branch. +In this case, deploy the `main` branch to staging. +To deploy to pre-production, create a merge request from the `main` branch to the pre-production branch. Go live by merging the pre-production branch into the production branch. This workflow, where commits only flow downstream, ensures that everything is tested in all environments. -If you need to cherry-pick a commit with a hotfix, it is common to develop it on a feature branch and merge it into `master` with a merge request. +If you need to cherry-pick a commit with a hotfix, it is common to develop it on a feature branch and merge it into `main` with a merge request. In this case, do not delete the feature branch yet. -If `master` passes automatic testing, you then merge the feature branch into the other branches. +If `main` passes automatic testing, you then merge the feature branch into the other branches. If this is not possible because more manual testing is required, you can send merge requests from the feature branch to the downstream branches. ## Release branches with GitLab flow @@ -117,15 +117,15 @@ If this is not possible because more manual testing is required, you can send me You only need to work with release branches if you need to release software to the outside world. In this case, each branch contains a minor version, such as `2-3-stable` or `2-4-stable`. -Create stable branches using `master` as a starting point, and branch as late as possible. +Create stable branches using `main` as a starting point, and branch as late as possible. By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches. After announcing a release branch, only add serious bug fixes to the branch. -If possible, first merge these bug fixes into `master`, and then cherry-pick them into the release branch. -If you start by merging into the release branch, you might forget to cherry-pick them into `master`, and then you'd encounter the same bug in subsequent releases. -Merging into `master` and then cherry-picking into release is called an "upstream first" policy, which is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/en/blog/a-community-for-using-openstack-with-red-hat-rdo). +If possible, first merge these bug fixes into `main`, and then cherry-pick them into the release branch. +If you start by merging into the release branch, you might forget to cherry-pick them into `main`, and then you'd encounter the same bug in subsequent releases. +Merging into `main` and then cherry-picking into release is called an "upstream first" policy, which is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/en/blog/a-community-for-using-openstack-with-red-hat-rdo). Every time you include a bug fix in a release branch, increase the patch version (to comply with [Semantic Versioning](https://semver.org/)) by setting a new tag. Some projects also have a stable branch that points to the same commit as the latest released branch. -In this flow, it is not common to have a production branch (or Git flow `master` branch). +In this flow, it is not common to have a production branch (or Git flow `main` branch). ## Merge/pull requests with GitLab flow @@ -151,8 +151,9 @@ Also, mention any other people from whom you would like feedback. After the assigned person feels comfortable with the result, they can merge the branch. If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging. -In GitLab, it is common to protect the long-lived branches, such as the `master` branch, so [most developers can't modify them](../user/permissions.md). -So, if you want to merge into a protected branch, assign your merge request to someone with maintainer permissions. +In GitLab, it is common to protect the long-lived branches, such as the `main` branch, so [most developers can't modify them](../user/permissions.md). +So, if you want to merge into a protected branch, assign your merge request to someone with the +[Maintainer role](../user/permissions.md). After you merge a feature branch, you should remove it from the source control software. In GitLab, you can do this when merging. @@ -178,7 +179,7 @@ In many organizations, raising an issue is part of the development process becau The issue title should describe the desired state of the system. For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Administrators can't remove users." -When you are ready to code, create a branch for the issue from the `master` branch. +When you are ready to code, create a branch for the issue from the `main` branch. This branch is the place for any work related to this change. NOTE: @@ -188,11 +189,11 @@ When you are done or want to discuss the code, open a merge request. A merge request is an online place to discuss the change and review the code. If you open the merge request but do not assign it to anyone, it is a [draft merge request](../user/project/merge_requests/drafts.md). -These are used to discuss the proposed implementation but are not ready for inclusion in the `master` branch yet. +These are used to discuss the proposed implementation but are not ready for inclusion in the `main` branch yet. Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to prevent it from being merged before it's ready. When you think the code is ready, assign the merge request to a reviewer. -The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch. +The reviewer can merge the changes when they think the code is ready for inclusion in the `main` branch. When they press the merge button, GitLab merges the code and creates a merge commit that makes this event visible later on. Merge requests always create a merge commit, even when the branch could be merged without one. This merge strategy is called "no fast-forward" in Git. @@ -247,18 +248,18 @@ Git does not allow you to merge the code again otherwise. Having lots of merge commits can make your repository history messy. Therefore, you should try to avoid merge commits in feature branches. -Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `master` branch. -Using rebase prevents a merge commit when merging `master` into your feature branch, and it creates a neat linear history. +Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `main` branch. +Using rebase prevents a merge commit when merging `main` into your feature branch, and it creates a neat linear history. However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should avoid rebasing commits in a feature branch that you're sharing with others. Rebasing could create more work, as every time you rebase, you may need to resolve the same conflicts. Sometimes you can reuse recorded resolutions (`rerere`), but merging is better, because you only have to resolve conflicts once. Atlassian has a more thorough explanation of the tradeoffs between merging and rebasing [on their blog](https://www.atlassian.com/blog/git/git-team-workflows-merge-or-rebase). -A good way to prevent creating many merge commits is to not frequently merge `master` into the feature branch. -There are three reasons to merge in `master`: utilizing new code, resolving merge conflicts, and updating long-running branches. +A good way to prevent creating many merge commits is to not frequently merge `main` into the feature branch. +There are three reasons to merge in `main`: utilizing new code, resolving merge conflicts, and updating long-running branches. -If you need to use some code that was introduced in `master` after you created the feature branch, you can often solve this by just cherry-picking a commit. +If you need to use some code that was introduced in `main` after you created the feature branch, you can often solve this by just cherry-picking a commit. If your feature branch has a merge conflict, creating a merge commit is a standard way of solving this. @@ -272,9 +273,9 @@ Most feature branches should take less than one day of work. If your feature branches often take more than a day of work, try to split your features into smaller units of work. If you need to keep a feature branch open for more than a day, there are a few strategies to keep it up-to-date. -One option is to use continuous integration (CI) to merge in `master` at the start of the day. +One option is to use continuous integration (CI) to merge in `main` at the start of the day. Another option is to only merge in from well-defined points in time, for example, a tagged release. -You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggle.html) to hide incomplete features so you can still merge back into `master` every day. +You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggle.html) to hide incomplete features so you can still merge back into `main` every day. NOTE: Don't confuse automatic branch testing with continuous integration. @@ -327,26 +328,26 @@ Issue: gitlab.com/gitlab-org/gitlab/-/issues/1  -In old workflows, the continuous integration (CI) server commonly ran tests on the `master` branch only. -Developers had to ensure their code did not break the `master` branch. -When using GitLab flow, developers create their branches from this `master` branch, so it is essential that it never breaks. +In old workflows, the continuous integration (CI) server commonly ran tests on the `main` branch only. +Developers had to ensure their code did not break the `main` branch. +When using GitLab flow, developers create their branches from this `main` branch, so it is essential that it never breaks. Therefore, each merge request must be tested before it is accepted. CI software like Travis CI and GitLab CI/CD show the build results right in the merge request itself to simplify the process. There is one drawback to testing merge requests: the CI server only tests the feature branch itself, not the merged result. -Ideally, the server could also test the `master` branch after each change. -However, retesting on every commit to `master` is computationally expensive and means you are more frequently waiting for test results. +Ideally, the server could also test the `main` branch after each change. +However, retesting on every commit to `main` is computationally expensive and means you are more frequently waiting for test results. Because feature branches should be short-lived, testing just the branch is an acceptable risk. -If new commits in `master` cause merge conflicts with the feature branch, merge `master` back into the branch to make the CI server re-run the tests. +If new commits in `main` cause merge conflicts with the feature branch, merge `main` back into the branch to make the CI server re-run the tests. As said before, if you often have feature branches that last for more than a few days, you should make your issues smaller. ## Working with feature branches  -When creating a feature branch, always branch from an up-to-date `master`. +When creating a feature branch, always branch from an up-to-date `main`. If you know before you start that your work depends on another branch, you can also branch from there. If you need to merge in another branch after starting, explain the reason in the merge commit. -If you have not pushed your commits to a shared location yet, you can also incorporate changes by rebasing on `master` or another feature branch. +If you have not pushed your commits to a shared location yet, you can also incorporate changes by rebasing on `main` or another feature branch. Do not merge from upstream again if your code can work and merge cleanly without doing so. -Merging only when needed prevents creating merge commits in your feature branch that later end up littering the `master` history. +Merging only when needed prevents creating merge commits in your feature branch that later end up littering the `main` history. |