From 58c212671690562fa507221a70fb8af04eecf648 Mon Sep 17 00:00:00 2001 From: Preston Vasquez Date: Tue, 6 May 2025 18:14:04 -0600 Subject: [PATCH 1/8] GODRIVER-3550 Update Documentation for Go Driver Branching and Merge Strategies --- docs/CONTRIBUTING.md | 82 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 80 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 0c39558c66..4f0458e7ad 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -30,8 +30,6 @@ If any tests do not pass, or relevant tests are not included, the patch will not If you are working on a bug or feature listed in Jira, please include the ticket number prefixed with GODRIVER in the commit message and GitHub pull request title, (e.g. GODRIVER-123). For the patch commit message itself, please follow the [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) guide. -\======= - ### Linting on commit The Go team uses [pre-commit](https://pre-commit.com/#installation) to lint both source and text files. @@ -49,6 +47,86 @@ After that, the checks will run on any changed files when committing. To manual pre-commit run --all-files ``` +### Merge up GitHub Action + +PR [#1962](https://github.com/mongodb/mongo-go-driver/pull/1962) added the "Merge up" GitHub Actions workflow to automatically roll changes from old branches into new ones. This section outlines how this process works. + +#### Regression + +If a regression is identified in the release/2.x branch, a fix should be submitted as a pull request targeting +release/2.x. Once this PR is merged, the "Merge up" GitHub Action will automatically create a pull request to merge +release/2.x into release/2.x+1. This process is repeated until changes are merged all the way up to release/2.latest, +which is then merged into the master branch. + +For example, suppose we have four minor release branches: release/2.0, release/2.1, release/2.2, and release/2.3. If a +regression is identified in the release/2.1 branch, you would first create a pull request to fix the issue in +release/2.1. Once this pull request is merged, the "Merge up" GitHub Action automatically initiates a pull request to +merge the changes from release/2.1 into release/2.2. After that merge is completed, the action continues to create a +pull request to merge release/2.2 into release/2.3. Finally, once the changes have successfully rolled through all the +release branches, the updates in release/2.3 are prepared to be merged into the master branch, ensuring all the bug +fixes are incorporated into the latest codebase. + +```mermaid +gitGraph + commit tag: "Initial main setup" + + branch release/2.0 + checkout release/2.0 + commit tag: "Initial release/2.0" + + branch release/2.1 + checkout release/2.1 + commit tag: "Bug introduced" + + branch release/2.2 + checkout release/2.2 + commit tag: "Initial release/2.2" + + branch release/2.3 + checkout release/2.3 + commit tag: "Initial release/2.3" + + checkout release/2.1 + commit tag: "Bug fix in release/2.1 (Manual PR)" + + checkout release/2.2 + merge release/2.1 tag: "Merge fix from release/2.1 (GitHub Actions)" + commit + + checkout release/2.3 + merge release/2.2 tag: "Merge updates from release/2.2 (GitHub Actions)" + commit + + checkout main + merge release/2.3 tag: "Merge updates from release/2.3 (Github Actions)" + commit +``` + +#### Pull Request Management + +When the "Merge up" GitHub Action is enabled, multiple merge-up pull requests (such as PR1, PR2, and PR3) can be +automatically created at the same time for different bug fixes or features that all target, for example, the +release/2.x branch. At first, PR1, PR2, and PR3 exist side by side—each handling separate changes. When PR1 and PR2 are +closed (merged), the Action automatically combines their changes into PR3. This final PR3 then contains all updates, +allowing you to merge everything into release/2.x+1 in a single, streamlined step. + +```mermaid +flowchart LR + A[PR1: Merge up from release/2.x] --> B[Close PR1] + C[PR2: Merge up from release/2.x] --> D[Close PR2] + + B --> E[PR3: Consolidated Final Pull Request] + D --> E + E --> F[release/2.x+1] + B[Close PR1] + D[Close PR2] + E[PR3: Includes changes from both PR1 and PR2] +``` + +#### Evergreen Config Merge Strategy + +Changes to the testing workflow should persist through all releases in a major version. + ### Cherry-picking between branches #### Using the GitHub App From 320fb93240109b39590a94f8c8804e1e8af7142f Mon Sep 17 00:00:00 2001 From: Preston Vasquez Date: Tue, 6 May 2025 18:24:44 -0600 Subject: [PATCH 2/8] GODRIVER-3550 Update the mermaid graph --- docs/CONTRIBUTING.md | 51 +++++++++++++++++++++++--------------------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4f0458e7ad..9fbd9304fa 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -68,38 +68,41 @@ fixes are incorporated into the latest codebase. ```mermaid gitGraph - commit tag: "Initial main setup" + commit tag: "Initial main setup" - branch release/2.0 - checkout release/2.0 - commit tag: "Initial release/2.0" + branch release/2.0 + checkout release/2.0 + commit tag: "Initial release/2.0" - branch release/2.1 - checkout release/2.1 - commit tag: "Bug introduced" + checkout main + branch release/2.1 + checkout release/2.1 + commit tag: "Bug introduced" - branch release/2.2 - checkout release/2.2 - commit tag: "Initial release/2.2" + checkout main + branch release/2.2 + checkout release/2.2 + commit tag: "Initial release/2.2" - branch release/2.3 - checkout release/2.3 - commit tag: "Initial release/2.3" + checkout main + branch release/2.3 + checkout release/2.3 + commit tag: "Initial release/2.3" - checkout release/2.1 - commit tag: "Bug fix in release/2.1 (Manual PR)" + checkout release/2.1 + commit tag: "Bug fix in release/2.1 (Manual PR)" - checkout release/2.2 - merge release/2.1 tag: "Merge fix from release/2.1 (GitHub Actions)" - commit + checkout release/2.2 + merge release/2.1 tag: "Merge fix from release/2.1 (GitHub Actions)" + commit - checkout release/2.3 - merge release/2.2 tag: "Merge updates from release/2.2 (GitHub Actions)" - commit + checkout release/2.3 + merge release/2.2 tag: "Merge updates from release/2.2 (GitHub Actions)" + commit - checkout main - merge release/2.3 tag: "Merge updates from release/2.3 (Github Actions)" - commit + checkout main + merge release/2.3 tag: "Merge updates from release/2.3 (GitHub Actions)" + commit ``` #### Pull Request Management From 5bb0e26d86f397b079219a9060f05661b202365f Mon Sep 17 00:00:00 2001 From: Preston Vasquez Date: Tue, 6 May 2025 18:29:16 -0600 Subject: [PATCH 3/8] GODRIVER-3550 merged <> closed --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9fbd9304fa..802ea3bbf3 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -110,7 +110,7 @@ gitGraph When the "Merge up" GitHub Action is enabled, multiple merge-up pull requests (such as PR1, PR2, and PR3) can be automatically created at the same time for different bug fixes or features that all target, for example, the release/2.x branch. At first, PR1, PR2, and PR3 exist side by side—each handling separate changes. When PR1 and PR2 are -closed (merged), the Action automatically combines their changes into PR3. This final PR3 then contains all updates, +closed, the Action automatically combines their changes into PR3. This final PR3 then contains all updates, allowing you to merge everything into release/2.x+1 in a single, streamlined step. ```mermaid From 88c52461f478e3aa0969de8b5ba2f0a4c3933545 Mon Sep 17 00:00:00 2001 From: Preston Vasquez Date: Tue, 6 May 2025 22:00:07 -0600 Subject: [PATCH 4/8] GODRIVER-3550 Note that we typically merge into current release --- docs/CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 802ea3bbf3..06aed84bb1 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -53,7 +53,7 @@ PR [#1962](https://github.com/mongodb/mongo-go-driver/pull/1962) added the "Merg #### Regression -If a regression is identified in the release/2.x branch, a fix should be submitted as a pull request targeting +If a regression is identified in the release/2.x branch, a fix can be submitted as a pull request targeting release/2.x. Once this PR is merged, the "Merge up" GitHub Action will automatically create a pull request to merge release/2.x into release/2.x+1. This process is repeated until changes are merged all the way up to release/2.latest, which is then merged into the master branch. @@ -105,6 +105,8 @@ gitGraph commit ``` +**Note**: In general, bug fixes should only target the latest release branch, since we only support patching the latest version. However, this is just a rule of thumb—exceptions can be made when necessary. + #### Pull Request Management When the "Merge up" GitHub Action is enabled, multiple merge-up pull requests (such as PR1, PR2, and PR3) can be From b6e646252a0dbe9f062dfad1ec44cb92c7e532d0 Mon Sep 17 00:00:00 2001 From: Preston Vasquez Date: Tue, 6 May 2025 22:06:17 -0600 Subject: [PATCH 5/8] GODRIVER-3550 Clean up wording --- docs/CONTRIBUTING.md | 51 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 06aed84bb1..cc2e1bd9e3 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -66,6 +66,55 @@ pull request to merge release/2.2 into release/2.3. Finally, once the changes ha release branches, the updates in release/2.3 are prepared to be merged into the master branch, ensuring all the bug fixes are incorporated into the latest codebase. +If a regression is identified in an older branch, the fix should be applied directly to the latest +release branch. Once the pull request with the fix is merged into latest, the "Merge up" GitHub Action will +automatically create a pull request to merge these changes into the master branch. This ensures that all bug fixes are +incorporated into the latest codebase and actively supported versions. + +For example, suppose we have four minor release branches: release/2.0, release/2.1, release/2.2, and release/2.3. If a +regression is found in the release/2.1 branch, you would create a pull request to fix the issue in the latest supported +branch, release/2.3. Once this pull request is merged, the "Merge up" GitHub Action will automatically create a pull +request to merge the changes from release/2.3 into the master branch. + +``` +gitGraph + commit tag: "Initial main setup" + + branch release/2.0 + checkout release/2.0 + commit tag: "Initial release/2.0" + + checkout main + branch release/2.1 + checkout release/2.1 + commit tag: "Bug introduced" + + checkout main + branch release/2.2 + checkout release/2.2 + commit tag: "Initial release/2.2" + + checkout main + branch release/2.3 + checkout release/2.3 + commit tag: "Initial release/2.3" + + checkout release/2.1 + commit tag: "Bug found in release/2.1" + + checkout release/2.3 + commit tag: "Bug fix applied in release/2.3 (Manual PR)" + + checkout main + merge release/2.3 tag: "Merge fix from release/2.3 into master (GitHub Actions)" + commit +``` + +However, it is also possible to apply the fix to the older branch where the bug was originally found. In our example, +once the pull request is merged into release/2.1, the "Merge up" GitHub Action will initiate a series of pull requests +to roll the fix forward: first into release/2.2, then into release/2.3, and finally into master. This process makes sure +that the change cascades through every intermediate supported version. + ```mermaid gitGraph commit tag: "Initial main setup" @@ -105,8 +154,6 @@ gitGraph commit ``` -**Note**: In general, bug fixes should only target the latest release branch, since we only support patching the latest version. However, this is just a rule of thumb—exceptions can be made when necessary. - #### Pull Request Management When the "Merge up" GitHub Action is enabled, multiple merge-up pull requests (such as PR1, PR2, and PR3) can be From a48900ca1f96e9b47554ebc7306d3f2ec0d19b23 Mon Sep 17 00:00:00 2001 From: Preston Vasquez Date: Tue, 6 May 2025 22:07:27 -0600 Subject: [PATCH 6/8] GODRIVER-3550 format as mermaid --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index cc2e1bd9e3..f43b99044a 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -76,7 +76,7 @@ regression is found in the release/2.1 branch, you would create a pull request t branch, release/2.3. Once this pull request is merged, the "Merge up" GitHub Action will automatically create a pull request to merge the changes from release/2.3 into the master branch. -``` +```mermaid gitGraph commit tag: "Initial main setup" From d34f3bb57666abf975db7ccf2a18d0e78954bd1f Mon Sep 17 00:00:00 2001 From: Preston Vasquez Date: Tue, 6 May 2025 22:08:17 -0600 Subject: [PATCH 7/8] GODRIVER-3550 Remove old paragraph --- docs/CONTRIBUTING.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index f43b99044a..f008b4d626 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -53,19 +53,6 @@ PR [#1962](https://github.com/mongodb/mongo-go-driver/pull/1962) added the "Merg #### Regression -If a regression is identified in the release/2.x branch, a fix can be submitted as a pull request targeting -release/2.x. Once this PR is merged, the "Merge up" GitHub Action will automatically create a pull request to merge -release/2.x into release/2.x+1. This process is repeated until changes are merged all the way up to release/2.latest, -which is then merged into the master branch. - -For example, suppose we have four minor release branches: release/2.0, release/2.1, release/2.2, and release/2.3. If a -regression is identified in the release/2.1 branch, you would first create a pull request to fix the issue in -release/2.1. Once this pull request is merged, the "Merge up" GitHub Action automatically initiates a pull request to -merge the changes from release/2.1 into release/2.2. After that merge is completed, the action continues to create a -pull request to merge release/2.2 into release/2.3. Finally, once the changes have successfully rolled through all the -release branches, the updates in release/2.3 are prepared to be merged into the master branch, ensuring all the bug -fixes are incorporated into the latest codebase. - If a regression is identified in an older branch, the fix should be applied directly to the latest release branch. Once the pull request with the fix is merged into latest, the "Merge up" GitHub Action will automatically create a pull request to merge these changes into the master branch. This ensures that all bug fixes are From 06aaac8f9ba59383edbbcae51445caad55d185b8 Mon Sep 17 00:00:00 2001 From: Preston Vasquez Date: Tue, 6 May 2025 22:10:33 -0600 Subject: [PATCH 8/8] GODRIVER-3550 wording cleanup --- docs/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index f008b4d626..cd67cdaee3 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -61,7 +61,7 @@ incorporated into the latest codebase and actively supported versions. For example, suppose we have four minor release branches: release/2.0, release/2.1, release/2.2, and release/2.3. If a regression is found in the release/2.1 branch, you would create a pull request to fix the issue in the latest supported branch, release/2.3. Once this pull request is merged, the "Merge up" GitHub Action will automatically create a pull -request to merge the changes from release/2.3 into the master branch. +request to merge the changes from release/2.3 into the master branch. Then you can proceed to release release/2.3.latest+1. ```mermaid gitGraph @@ -97,7 +97,7 @@ gitGraph commit ``` -However, it is also possible to apply the fix to the older branch where the bug was originally found. In our example, +If necessary, it is also possible to apply the fix to the older branch where the bug was originally found. In our example, once the pull request is merged into release/2.1, the "Merge up" GitHub Action will initiate a series of pull requests to roll the fix forward: first into release/2.2, then into release/2.3, and finally into master. This process makes sure that the change cascades through every intermediate supported version.