Add latest changes from gitlab-org/gitlab@master
This commit is contained in:
GitLab Bot
parent
ea2247e08d
commit
a43ce769df
|
|
@ -4,6 +4,6 @@ feature_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/511506
|
|||
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/180331
|
||||
rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/517917
|
||||
milestone: '17.9'
|
||||
type: development
|
||||
type: beta
|
||||
group: group::source code
|
||||
default_enabled: false
|
||||
default_enabled: true
|
||||
|
|
@ -269,7 +269,7 @@ See the [test engineering process](https://handbook.gitlab.com/handbook/engineer
|
|||
1. You have included changelog trailers, or you have decided that they are not needed.
|
||||
- [Does this MR need a changelog?](changelog.md#what-warrants-a-changelog-entry)
|
||||
1. You have added/updated documentation or decided that documentation changes are unnecessary for this MR.
|
||||
- [Is documentation required?](https://handbook.gitlab.com/handbook/product/ux/technical-writing/workflow/#documentation-for-a-product-change)
|
||||
- [Is documentation required?](documentation/workflow.md#documentation-for-a-product-change)
|
||||
|
||||
##### Security
|
||||
|
||||
|
|
|
|||
|
|
@ -53,6 +53,337 @@ For example, if you move a page, but also update the content of the page:
|
|||
You can add as many commits as you want, but make sure the first commit only moves the content,
|
||||
and does not edit it.
|
||||
|
||||
## Documentation for a product change
|
||||
|
||||
Documentation is required for any new or changed feature, and is:
|
||||
|
||||
- Created or updated as part of feature development, and is almost always in
|
||||
the same merge request as the feature code. Including documentation in the
|
||||
same merge request as the code eliminates the possibility that code and
|
||||
documentation get out-of-sync.
|
||||
- Required with the delivery of a feature for a specific milestone as part of the
|
||||
GitLab [definition of done](../contributing/merge_request_workflow.md#definition-of-done).
|
||||
- Linked from the release post.
|
||||
|
||||
### Developer responsibilities
|
||||
|
||||
Developers are the primary authors of documentation for a feature or feature
|
||||
enhancement. They are responsible for:
|
||||
|
||||
- Developing initial content required for a feature.
|
||||
- Liaising with their Product Manager to understand what documentation must be
|
||||
delivered, and when.
|
||||
- Requesting technical reviews from other developers in their group.
|
||||
- Requesting documentation reviews from the Technical Writer
|
||||
[assigned to the DevOps stage group](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments)
|
||||
that is delivering the new feature or feature enhancements.
|
||||
|
||||
The first merge request where a feature can be tested should include the
|
||||
documentation, even if the feature is behind a feature flag.
|
||||
For more information, see the [guidelines](../documentation/feature_flags.md).
|
||||
|
||||
The author of this MR, either a frontend or backend developer, should write the documentation.
|
||||
|
||||
{{< alert type="note" >}}
|
||||
|
||||
Community Contributors can ask for additional help from GitLab team members.
|
||||
|
||||
{{< /alert >}}
|
||||
|
||||
#### Authoring
|
||||
|
||||
Because the documentation is an essential part of the product, if a `~"type::feature"`
|
||||
issue also contains the `~documentation` label, you must ship the new or
|
||||
updated documentation with the code of the feature.
|
||||
|
||||
Technical Writers are happy to help, as requested and planned on an
|
||||
issue-by-issue basis.
|
||||
|
||||
For feature issues requiring documentation, follow the process below unless
|
||||
otherwise agreed with the Product Manager and Technical Writer:
|
||||
|
||||
- Include any new and edited documentation, either in:
|
||||
- The merge request introducing the code.
|
||||
- A separate merge request raised around the same time.
|
||||
- Use the [documentation requirements](#documentation-requirements) developed
|
||||
by the Product Manager in the issue and discuss any further documentation
|
||||
plans or ideas as needed.
|
||||
|
||||
If the new or changed documentation requires extensive collaboration or
|
||||
conversation, a separate, linked issue can be used for the planning process.
|
||||
|
||||
- Use the [Documentation guidelines](../documentation/_index.md),
|
||||
and other resources linked from there, including:
|
||||
- [Documentation folder structure](site_architecture/folder_structure.md).
|
||||
- [Documentation Style Guide](styleguide/_index.md).
|
||||
- [Markdown Guide](../../user/markdown.md).
|
||||
- Contact the Technical Writer for the relevant
|
||||
[DevOps stage](https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments)
|
||||
in your issue or merge request, or in the `#docs` Slack channel, if you:
|
||||
- Need any help to choose the correct place for documentation.
|
||||
- Want to discuss a documentation idea or outline.
|
||||
- Want to request any other help.
|
||||
- If you are working on documentation in a separate merge request, ensure the
|
||||
documentation is merged as close as possible to the code merge.
|
||||
- If the feature has a feature flag, [follow the policy for documenting feature-flagged issues](../documentation/feature_flags.md).
|
||||
|
||||
#### Review
|
||||
|
||||
Before merging, documentation changes committed by the developer must be
|
||||
reviewed by:
|
||||
|
||||
- The code reviewer for the merge request. This is known as a technical review.
|
||||
- Optionally, others involved in the work such as other developers or the
|
||||
Product Manager.
|
||||
- The Technical Writer for the DevOps stage group, except in exceptional
|
||||
circumstances where a [post-merge review](#post-merge-reviews)
|
||||
can be requested.
|
||||
- A maintainer of the project.
|
||||
|
||||
### Product Manager responsibilities
|
||||
|
||||
Product Managers are responsible for the
|
||||
[documentation requirements](#documentation-requirements) for a feature or
|
||||
feature enhancement. They can also:
|
||||
|
||||
- Connect with the Technical Writer for discussion and collaboration.
|
||||
- Review documentation themselves.
|
||||
|
||||
For issues requiring any new or updated documentation, the Product Manager
|
||||
must:
|
||||
|
||||
- Add the `~documentation` label.
|
||||
- Confirm or add the documentation requirements.
|
||||
- Ensure the issue contains:
|
||||
- Any new or updated feature name.
|
||||
- Overview, description, and use cases when applicable (as required by the
|
||||
[documentation folder structure](site_architecture/folder_structure.md)).
|
||||
|
||||
Everyone is encouraged to draft the documentation requirements in the issue.
|
||||
However, a Product Manager will:
|
||||
|
||||
- When the issue is assigned a release milestone, review and update the
|
||||
Documentation details.
|
||||
- By the kickoff, finalize the documentation details.
|
||||
|
||||
### Technical Writer responsibilities
|
||||
|
||||
Technical Writers are responsible for:
|
||||
|
||||
- Participating in issue discussions and reviewing MRs for the upcoming
|
||||
milestone.
|
||||
- Reviewing documentation requirements in issues when called upon.
|
||||
- Answering questions, and helping and providing advice throughout the
|
||||
authoring and editing process.
|
||||
- Reviewing all significant new and updated documentation content, whether
|
||||
before merge or after it is merged.
|
||||
- Assisting the developer and Product Manager with feature documentation
|
||||
delivery.
|
||||
- Ensuring that issues and MRs are labeled appropriately, and that doc content has the correct [metadata](metadata.md).
|
||||
|
||||
#### Planning
|
||||
|
||||
The Technical Writer:
|
||||
|
||||
- Reviews their group's `~"type::feature"` issues that are part of the next milestone
|
||||
to get a sense of the scope of content likely to be authored.
|
||||
- Recommends the `~documentation` label on issues from that list which don't
|
||||
have it but should, or inquires with the PM to determine if documentation is
|
||||
truly required.
|
||||
- For `~direction` issues from that list, reads the full issue and reviews its
|
||||
Documentation requirements section. Addresses any recommendations or
|
||||
questions with the PMs and others collaborating on the issue to
|
||||
refine or expand the Documentation requirements.
|
||||
- Updates the Technical Writing milestone plan ([example](https://gitlab.com/gitlab-org/technical-writing/team-tasks/-/issues/521) created from the [issue template](https://gitlab.com/gitlab-org/technical-writing/team-tasks/-/blob/main/.gitlab/issue_templates/tw-milestone-plan.md)).
|
||||
- Add a link to the board or filter that shows the planned documentation and UI text work for the upcoming milestone.
|
||||
- Confirm that the group PM or EM is aware of the planned work.
|
||||
|
||||
#### Collaboration
|
||||
|
||||
By default, the developer will work on documentation changes independently, but
|
||||
the developer, Product Manager, or Technical Writer can propose a broader
|
||||
collaboration for any given issue.
|
||||
|
||||
Additionally, Technical Writers are available for questions at any time.
|
||||
|
||||
#### Review
|
||||
|
||||
Technical Writers provide non-blocking reviews of all documentation changes, before or after
|
||||
the change is merged. Identified issues that would block or slow a change's
|
||||
release are to be handled in linked, follow-up MRs.
|
||||
|
||||
### Documentation requirements
|
||||
|
||||
Feature documentation requirements should be included as part of
|
||||
the issue for planning that feature in the **Documentation** section in the
|
||||
issue description. Issues created using the
|
||||
[**Feature Proposal** template](https://gitlab.com/gitlab-org/gitlab/-/raw/master/.gitlab/issue_templates/Feature%20proposal%20-%20detailed.md)
|
||||
have this section by default.
|
||||
|
||||
Anyone can add these details, but the Product Manager who assigns the issue to
|
||||
a specific release milestone will ensure these details are present and
|
||||
finalized by the time of that milestone's kickoff.
|
||||
|
||||
Developers, Technical Writers, and others may help further refine this plan at
|
||||
any time on request.
|
||||
|
||||
The following details should be included:
|
||||
|
||||
- What concepts and procedures should the documentation guide and enable the
|
||||
user to understand or accomplish?
|
||||
- To this end, what new pages are needed, if any? What pages or subsections
|
||||
need updates? Consider changes and additions to user, admin, and API
|
||||
documentation.
|
||||
- For any guide or instruction set, should it help address a single use case,
|
||||
or be flexible to address a certain range of use cases?
|
||||
- Do we need to update a previously recommended workflow? Should we link the
|
||||
new feature from various relevant locations? Consider all ways documentation
|
||||
should be affected.
|
||||
- Are there any key terms or task descriptions that should be included so that
|
||||
the documentation is found in relevant searches?
|
||||
- Include suggested titles of any pages or subsection headings, if applicable.
|
||||
- List any documentation that should be cross-linked, if applicable.
|
||||
|
||||
### Including documentation with code
|
||||
|
||||
Currently, the Technical Writing team strongly encourages including
|
||||
documentation in the same merge request as the code that it relates to, but
|
||||
this isn't strictly mandatory. It's still common for documentation to be added
|
||||
in an MR separate from the feature MR.
|
||||
|
||||
Engineering teams may elect to adopt a workflow where it is **mandatory** that
|
||||
documentation is included in the code MR, as part of their
|
||||
[definition of done](../contributing/merge_request_workflow.md#definition-of-done).
|
||||
When a team adopts this workflow, that team's engineers must include their
|
||||
documentation in the **same** MR as their feature code, at all times.
|
||||
|
||||
#### Downsides of separate documentation MRs
|
||||
|
||||
A workflow that has documentation separated into its own MR has many downsides.
|
||||
|
||||
If the documentation merges **before** the feature:
|
||||
|
||||
- GitLab.com users might try to use the feature before it's released, driving
|
||||
support tickets.
|
||||
- If the feature is delayed, the documentation might not be pulled/reverted in
|
||||
time and could be accidentally included on GitLab Self-Managed for that
|
||||
release.
|
||||
|
||||
If the documentation merges **after** the feature:
|
||||
|
||||
- The feature might be included on GitLab Self-Managed, but without any
|
||||
documentation if the documentation MR misses the cutoff.
|
||||
- A feature might show up in the GitLab.com user interface before any
|
||||
documentation exists for it. Users surprised by this feature will search for
|
||||
documentation and won't find it, possibly driving support tickets.
|
||||
|
||||
Having two separate MRs means:
|
||||
|
||||
- Two different people might be responsible for merging one feature, which
|
||||
isn't workable with an asynchronous work style. The feature might merge while
|
||||
the Technical Writer is asleep, creating a potentially lengthy delay between
|
||||
the two merges.
|
||||
- If the documentation MR is assigned to the same maintainer as responsible for
|
||||
the feature code MR, they will have to review and juggle two MRs instead of
|
||||
dealing with just one.
|
||||
|
||||
Documentation quality might be lower, because:
|
||||
|
||||
- Having documentation in a separate MR will mean far fewer people will see and
|
||||
verify them, increasing the likelihood that issues will be missed.
|
||||
- In a *split* workflow, engineers might only create the documentation MR after
|
||||
the feature MR is ready, or almost ready. This gives the Technical Writer
|
||||
little time to learn about the feature to do a good review. It also
|
||||
increases pressure on them to review and merge faster than desired, letting
|
||||
problems slip in due to haste.
|
||||
|
||||
#### Benefits of always including documentation with code
|
||||
|
||||
Including documentation with code (and doing it early in the development
|
||||
process) has many benefits:
|
||||
|
||||
- There are no timing issues connected to releases:
|
||||
- If a feature slips to the next release, the documentation slips too.
|
||||
- If the feature *just* makes it into a release, the documentation *just*
|
||||
makes it in too.
|
||||
- If a feature makes it to GitLab.com early, the documentation will be ready
|
||||
for our early adopters.
|
||||
- Only a single person will be responsible for merging the feature (the code
|
||||
maintainer).
|
||||
- The Technical Writer will have more time to gain an understanding of the
|
||||
feature and will be better able to verify the content of the documentation in
|
||||
the Review App or GDK. They will also be able to offer advice for improving
|
||||
the user interface text or offer additional use cases.
|
||||
- The documentation will have increased visibility:
|
||||
- Everyone involved in the merge request can review the documentation. This
|
||||
could include product managers, multiple engineers with deep domain
|
||||
knowledge, the code reviewers, and the maintainer. They will be more likely
|
||||
to catch issues with examples, and background or concepts that the
|
||||
Technical Writer may not be aware of.
|
||||
- Increasing visibility of the documentation also has the side effect of
|
||||
improving *other* engineers' documentation. By reviewing each other's MRs,
|
||||
each engineer's own documentation skills will improve.
|
||||
- Thinking about the documentation early can help engineers generate better
|
||||
examples, as they will need to think about what examples a user will want,
|
||||
and will need to ensure the code they write implements that example properly.
|
||||
|
||||
#### Documentation with code as a workflow
|
||||
|
||||
To have documentation included with code as a mandatory workflow, some
|
||||
changes might need to happen to a team's current workflow:
|
||||
|
||||
- The engineers must strive to include the documentation early in the
|
||||
development process, to give ample time for review, not just from the
|
||||
Technical Writer, but also the code reviewer and maintainer.
|
||||
- Reviewers and maintainers must also review the documentation during code
|
||||
reviews to ensure the described processes match the expected use of the
|
||||
feature and that examples are correct.
|
||||
They do **not** need to worry about style or grammar.
|
||||
- The Technical Writer must be assigned as a reviewer on the MR directly and not only pinged.
|
||||
This can be done at any time, but must be before the code maintainer review.
|
||||
It's common to have both the documentation and code reviews happening at the
|
||||
same time, with the author, reviewer, and Technical Writer discussing the
|
||||
documentation together.
|
||||
- When the documentation is ready, the Technical Writer will click **Approve**
|
||||
and usually will no longer be involved in the MR. If the feature changes
|
||||
during code review and the documentation is updated, the Technical Writer
|
||||
must be reassigned the MR to verify the update.
|
||||
- Maintainers are allowed to merge features with the documentation *as-is*,
|
||||
even if the Technical Writer hasn't given final approval yet. The
|
||||
**documentation reviews must not be blockers**. Therefore, it's important to
|
||||
get the documentation included and assigned to the Technical Writers early.
|
||||
If the feature is merged before final documentation approval, the maintainer
|
||||
must create a [post-merge follow-up issue](#post-merge-reviews),
|
||||
and assign it to both the engineer and Technical Writer.
|
||||
|
||||
You can visualize the parallel workflow for code and documentation reviews as:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A("Feature MR Created (Engineer)") --> |Assign| B("Code Review (reviewer)")
|
||||
B --> |"Approve / Reassign"| C("Code Review (maintainer)")
|
||||
C --> |Approve| F("Merge (maintainer)")
|
||||
A --> D("Docs Added (Engineer)")
|
||||
D --> |Assign| E("Docs Review (Tech Writer)")
|
||||
E --> |Approve| F
|
||||
```
|
||||
|
||||
For complex features split over multiple merge requests:
|
||||
|
||||
- If a merge request is implementing components for a future feature, but the
|
||||
components aren't accessible to users yet, then no documentation should be
|
||||
included.
|
||||
- If a merge request will expose a feature to users in any way, such as an
|
||||
enabled user interface element, an API endpoint, or anything similar, then
|
||||
that MR **must** have documentation. This might mean multiple
|
||||
documentation additions could happen in the buildup to the implementation of
|
||||
a single large feature, for example API documentation and feature usage
|
||||
documentation.
|
||||
- If it's unclear which engineer should add the feature documentation into
|
||||
their MR, the engineering manager should decide during planning, and tie the
|
||||
documentation to the last MR that must be merged before a feature is
|
||||
considered released. This is often, but not always, a frontend MR.
|
||||
|
||||
## Documentation labels
|
||||
|
||||
When you author an issue or merge request, choose the
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ title: Eclipse troubleshooting
|
|||
If the steps on this page don't solve your problem, check the
|
||||
[list of open issues](https://gitlab.com/gitlab-org/editor-extensions/gitlab-eclipse-plugin/-/issues/?sort=created_date&state=opened&first_page_size=100)
|
||||
in the Eclipse plugin's project. If an issue matches your problem, update the issue.
|
||||
If no issues match your problem, [create a new issue](https://gitlab.com/gitlab-org/editor-extensions/gitlab-eclipse-plugin/-/issues/new).
|
||||
If no issues match your problem, [create a new issue](https://gitlab.com/gitlab-org/editor-extensions/gitlab-eclipse-plugin/-/issues/new) with the [required information for support](#required-information-for-support).
|
||||
|
||||
## Review the Error Log
|
||||
|
||||
|
|
@ -45,6 +45,32 @@ The debug logs are available in the `language_server.log` file. To view this fil
|
|||
- Go to the directory `/Users/<user>/eclipse/<eclipse-version>/Eclipse.app/Contents/MacOS/.gitlab_plugin`, replacing `<user>` and `<eclipse-version>` with the appropriate values.
|
||||
- Open the [Error logs](#review-the-error-log). Search for the log `Language server logs saved to: <file>.` where `<file>` is the absolute path to the `language_server.log` file.
|
||||
|
||||
## Required information for support
|
||||
|
||||
When creating a support request, provide this information:
|
||||
|
||||
1. Your current GitLab for Eclipse plugin version.
|
||||
1. Open the `About Eclipse IDE` popup window.
|
||||
- On Windows, in your IDE, select **Help > About Eclipse IDE**.
|
||||
- On MacOS, in your IDE, select **Eclipse > About Eclipse IDE**.
|
||||
1. On the dialog, select **Installation details**.
|
||||
1. Locate **GitLab for Eclipse** and copy the **Version** value.
|
||||
|
||||
1. Your Eclipse version.
|
||||
1. Open the `About Eclipse IDE` popup window.
|
||||
- On Windows, in your IDE, select **Help > About Eclipse IDE**.
|
||||
- On MacOS, in your IDE, select **Eclipse > About Eclipse IDE**.
|
||||
|
||||
1. Your operating system.
|
||||
1. Are you using `gitlab.com` or a self-managed instance?
|
||||
1. Are you using a proxy?
|
||||
1. Are you using a self-signed certificate?
|
||||
1. The [workspace logs](#locate-the-workspace-log-file).
|
||||
1. The [Language Server debug logs](#enable-gitlab-language-server-debug-logs).
|
||||
1. If applicable, a video or a screenshot of the issue.
|
||||
1. If applicable, the steps to reproduce the issue.
|
||||
1. If applicable, the attempted steps to resolve the issue.
|
||||
|
||||
## Certificate errors
|
||||
|
||||
{{< alert type="warning" >}}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,221 @@
|
|||
---
|
||||
stage: Create
|
||||
group: Source Code
|
||||
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
|
||||
description: Expand your Git branching strategy when you outgrow the basic approach.
|
||||
title: Branching strategies
|
||||
---
|
||||
|
||||
The way you organize and merge Git branches is called a **branching strategy**.
|
||||
For many teams, the simplest approach is sensible and effective:
|
||||
|
||||
1. Make changes in a feature branch.
|
||||
1. Merge the feature branch directly to `main`.
|
||||
|
||||
However, if your team has complex needs (like testing and compliance requirements),
|
||||
you might want to consider a different branching strategy.
|
||||
|
||||
We want to demystify some of the more common strategies available.
|
||||
Not everyone has a Git (or version control) specialist on staff. If you know
|
||||
your team is working at the far edges of its Git skillset, this information is for you.
|
||||
|
||||
When you use GitLab to replace multiple, disparate tools, the decisions you
|
||||
make about your Git branching strategy matter. With careful planning, you can establish clear
|
||||
connections between:
|
||||
|
||||
- The initial bug reports you receive.
|
||||
- The commits your teams make to fix those bugs.
|
||||
- The processes of backporting those fixes to other versions or customers.
|
||||
- The deployments that make your fixes available to your users.
|
||||
|
||||
Careful choices help you take the best advantage of the single data store in GitLab.
|
||||
|
||||
## Do I need a more complex Git branching strategy?
|
||||
|
||||
You might have outgrown your current Git branching strategy if:
|
||||
|
||||
- You use continuous delivery.
|
||||
- You have significant automated testing.
|
||||
- You must fix critical bugs for one customer without affecting other customers.
|
||||
- You maintain multiple historical versions of your product.
|
||||
- Your product has no single production branch, because it supports multiple operating systems or platforms.
|
||||
- Your product has different deployment or certification requirements for each version.
|
||||
|
||||
Don't implement a strategy that is more complex than your product needs.
|
||||
|
||||
### When to split a project into multiple repositories
|
||||
|
||||
Should you maintain one Git repository with a complex branching structure, or split the project
|
||||
across multiple repositories? There's no single right answer. It depends on what you have the personnel
|
||||
and expertise to support.
|
||||
|
||||
GitLab provides automation that assumes your repository is for a single product, though that product
|
||||
might contain multiple versions. To determine if you should have multiple repositories, or a single
|
||||
complex one, ask these questions:
|
||||
|
||||
- Is it the same product?
|
||||
- Do all elements use the same build process?
|
||||
- Is the underlying code similar, or the same?
|
||||
|
||||
No matter what you choose (either a complex single repository, or a set of smaller repositories) you
|
||||
should expect to spend engineering time on maintenance. Identify which type of engineering work you are
|
||||
prepared to do:
|
||||
|
||||
- If you maintain code for multiple products in a single repository, plan for customization work later
|
||||
to use all features of GitLab.
|
||||
- Merging work across multiple repositories is more involved than merging across branches in the same
|
||||
repository. Plan for engineering time to build custom release processes and manage the flow of code
|
||||
across repositories.
|
||||
|
||||
{{< alert type="note" >}}
|
||||
Does your organization use a large monorepo or a megarepo? The
|
||||
[Professional Services](https://about.gitlab.com/services/) team at GitLab can help you construct a
|
||||
custom branching solution that meets your monorepo's needs.
|
||||
{{< /alert >}}
|
||||
|
||||
## Major types of branching strategies
|
||||
|
||||
Branching and code management strategies depend on your product's needs.
|
||||
No pre-existing strategy can cover them all, but we've identified some major categories:
|
||||
|
||||
- [Webservices](#webservices)
|
||||
- [Long-lived release branches](#long-lived-release-branches)
|
||||
- [A branch per environment](#branch-per-environment)
|
||||
|
||||
### Webservices
|
||||
|
||||
This strategy follows standard Git practices. The `main` branch is your production branch, which
|
||||
is great for a single webservice: there's one canonical production version, and no support for
|
||||
previous revisions.
|
||||
|
||||
For this configuration, [`git-flow`](https://nvie.com/posts/a-successful-git-branching-model/)
|
||||
probably works for you. It's standardized, and you don't have to maintain anything.
|
||||
|
||||
In this example, `feature-1` branches off directly from `main`. When complete, `feature-1` merges back
|
||||
directly into `main`. This merge commit is highlighted with a square. Longer-lived branches, like
|
||||
`feature-2`, might periodically merge in the latest updates from `main` as part of development.
|
||||
When complete, `feature-2` merges into `main`, and release `1.1` is cut:
|
||||
|
||||
```mermaid
|
||||
%%{init: { 'gitGraph': {'mainBranchOrder':1}} }%%
|
||||
gitGraph
|
||||
commit tag: "1.0" id: "release v1.0"
|
||||
branch "feature-1"
|
||||
commit id: "start feature-1"
|
||||
checkout main
|
||||
commit id: "start feature-2"
|
||||
branch "feature-2" order: 3
|
||||
checkout feature-1
|
||||
commit id: "refine feature-1"
|
||||
checkout main
|
||||
merge feature-1 type: HIGHLIGHT id: "merge feature-1 into main"
|
||||
checkout feature-2
|
||||
commit id: "build feature 2"
|
||||
merge main type: HIGHLIGHT id: "merge main into feature-2"
|
||||
commit
|
||||
checkout main
|
||||
merge feature-2 tag: "1.1" type: HIGHLIGHT id: "release v1.1"
|
||||
```
|
||||
|
||||
### Long-lived release branches
|
||||
|
||||
This branching strategy is appropriate if your product has branches that must remain separate from `main`
|
||||
for a long time. Some examples include:
|
||||
|
||||
- Multiple production versions of the same software package. For example: a current version, and
|
||||
legacy versions. The current version receives feature updates and hotfixes, while previous versions
|
||||
receive hotfixes and security releases only.
|
||||
- A current production version, and a long-lived beta version. You might need this approach when a major
|
||||
software dependency (like a software development kit, or SDK) is introducing breaking changes.
|
||||
The current production version receives feature updates and hotfixes. The beta version receives
|
||||
those feature updates and hotfixes while your team also builds in support for the upcoming SDK changes.
|
||||
|
||||
If you intend to lock a long-lived branch, it is critical to define your hotfix process and enforce it.
|
||||
If undefined and unenforced, every change becomes a hotfix.
|
||||
|
||||
In this example, the `2.0` branch is created from the commit on `main` for the `1.0` release.
|
||||
Features branch off from the `2.0` branch, and merge back into `2.0`. At the same time, any hotfix
|
||||
branches are based off of the most recent release (`1.0`) of `main`, and merge back into `main` as
|
||||
release `1.1`. The `2.0` branch then pulls in the changes from release `1.1`, and incorporates them
|
||||
as part of the development of `2.0`. After the addition of another feature (`feature-2`), the `2.0`
|
||||
branch is ready for production. It merges into `main`, and release `2.0` is cut:
|
||||
|
||||
```mermaid
|
||||
%%{init: { 'gitGraph': {'mainBranchOrder':2}} }%%
|
||||
gitGraph
|
||||
commit tag: "1.0"
|
||||
branch hotfix order: 1
|
||||
checkout main
|
||||
branch "2.0" order: 3
|
||||
commit
|
||||
checkout hotfix
|
||||
commit id: "security bug"
|
||||
commit id: "performance bug"
|
||||
checkout "2.0"
|
||||
branch feature-1 order: 4
|
||||
commit id: "create feature 1"
|
||||
checkout main
|
||||
commit id: " "
|
||||
checkout 2.0
|
||||
merge feature-1 id:"merge feature-1" tag: "2.0 RC 1"
|
||||
checkout main
|
||||
merge hotfix tag: "1.1" type: HIGHLIGHT
|
||||
checkout 2.0
|
||||
merge main tag: "2.0 RC 2" type: HIGHLIGHT
|
||||
branch feature-2 order: 5
|
||||
commit id: "create feature 2"
|
||||
commit id: "refine feature 2"
|
||||
checkout 2.0
|
||||
merge feature-2 id: "merge feature-2" tag: "2.0 RC 3"
|
||||
checkout main
|
||||
merge 2.0 tag: "2.0" type: HIGHLIGHT
|
||||
```
|
||||
|
||||
#### Migrate from SVN branching strategies
|
||||
|
||||
Legacy projects migrating from SVN to Git should review their branching approach.
|
||||
Some SVN-centric branching approaches in Git can prevent you from getting
|
||||
the most out of GitLab. Some workflows to revisit:
|
||||
|
||||
- You create a long-lived branch (like `1.0`) from `main`, then lock the `1.0` branch to block any
|
||||
change that is not a pre-approved hotfix.
|
||||
- Git handles merge conflicts better than SVN.
|
||||
- Avoid creating long-lived branches, unless you have contractual
|
||||
obligations to use them. While Git handles conflicts well, long-lived branches require you to
|
||||
spend time merging fixes to multiple branches.
|
||||
- You use branches because your product does not support feature flags.
|
||||
|
||||
### Branch per environment
|
||||
|
||||
This branching strategy is common for organizations with multiple interdependent services that are
|
||||
built by different teams. It's often used with waterfall or V-model development processes.
|
||||
|
||||
In this example, the commit marked `v1.1 RC1` is identified as a release candidate for version `1.1`.
|
||||
Features continue to branch from and back into `main`, while the release candidate commit is tested on
|
||||
the `test` and `UAT` environments. This process is repeated for each commit that is considered for release:
|
||||
|
||||
```mermaid
|
||||
gitGraph
|
||||
commit id: "start feature"
|
||||
branch feature-1
|
||||
checkout main
|
||||
commit tag: "v1.1 RC1" id: "start testing"
|
||||
branch test
|
||||
checkout feature-1
|
||||
commit id: "develop feature"
|
||||
commit id: "refine feature"
|
||||
checkout test
|
||||
commit id: " " tag: "v1.1 RC1"
|
||||
branch UAT
|
||||
checkout UAT
|
||||
commit tag: "v1.1"
|
||||
checkout main
|
||||
merge feature-1 id: "merge feature-1"
|
||||
commit
|
||||
```
|
||||
|
||||
## Related topics
|
||||
|
||||
- [Protected branches](../protected.md)
|
||||
- [Merge request approvals](../../../merge_requests/approvals/_index.md)
|
||||
- [Testing merged results](../../../../../ci/pipelines/merged_results_pipelines.md)
|
||||
Loading…
Reference in New Issue