From 13ee7e50f1bec0c056ce551945dd08cd52e2ed43 Mon Sep 17 00:00:00 2001 From: Donald Adu-Poku Date: Wed, 11 Sep 2019 16:20:07 +0000 Subject: [PATCH] docs: document module breaking changes process. This adds a section outlining the process to follow going forward with regards to making breaking changes to modules. --- docs/code_contribution_guidelines.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/code_contribution_guidelines.md b/docs/code_contribution_guidelines.md index bbc3f9a8..f9fdd757 100644 --- a/docs/code_contribution_guidelines.md +++ b/docs/code_contribution_guidelines.md @@ -7,6 +7,7 @@ 4.2. [Testing](#Testing)
4.3. [Code Documentation and Commenting](#CodeDocumentation)
4.4. [Model Git Commit Messages](#ModelGitCommitMessages)
+4.5. [Handling Module Breaking Changes](#HandlingModuleBreakingChanges)
5. [Code Approval Process](#CodeApproval)
5.1 [Code Review](#CodeReview)
5.2 [Rework Code (if needed)](#CodeRework)
@@ -269,6 +270,31 @@ a good thing. wrap our plain text emails such that there’s room for a few levels of nested reply indicators without overflow in an 80 column terminal. + + +### 4.5 Handling Module Breaking Changes + +Pull requests that introduce breaking changes to modules must ensure dependent +modules on the change are updated to referrence newly bumped module versions. +The purpose of this is to improve the release process by handling version +updates with the pull request that introduces it instead of waiting until +release. + +The request submitter should ensure the following steps are covered whenever a +new breaking change to a module's API is introduced: + +- Bump the major version in the `go.mod` of the affected module if not already + done since the last release tag. Note that v1 modules are stablilized even + without a release, breaking changes to such modules will require a major + version bump as well. +- Add a replacement to the `go.mod` in the main module if not already done since + the last release tag. +- Update all imports in the repo to use the new major version as necessary. + - Make necessary modifications to allow all other modules to use the new + version in the same commit. +- Repeat the process for any other modules the require a new major as a result + of consuming the new major(s). + ### 5. Code Approval Process