Document the process for bumping the major versionupgrade_docs

We need to document this so that releng and others can perform the bump
in the future.

Signed-off-by: Tim Smith <tsmith@chef.io>

4 files changed, 58 insertions, 5 deletions

diff --git a/docs/dev/how_to/building_and_installing.md b/docs/dev/how_to/building_and_installing.md
index e613de459a..9de9922108 100644
--- a/docs/dev/how_to/building_and_installing.md
+++ b/docs/dev/how_to/building_and_installing.md
@@ -1,8 +1,9 @@
 # Building and Installing
 
 Chef Infra can be built and installed in two distinct ways:
-	- A gem built from this repository and installed into your own Ruby installation
-	- A system native package containing its own Ruby built using our Omnibus packaging system
+
+- A gem built from this repository and installed into your own Ruby installation
+- A system native package containing its own Ruby built using our Omnibus packaging system
 
 **NOTE:** As an end user, please download the [Chef Infra package](https://downloads.chef.io/chef) for managing systems, or the [Chef Workstation package](https://downloads.chef.io/chef-workstation) for authoring Chef cookbooks and administering your Chef infrastructure.
 
diff --git a/docs/dev/how_to/bumping_minor_or_major_versions.md b/docs/dev/how_to/bumping_minor_or_major_versions.md
index ebcf4e4695..79cfa9075e 100644
--- a/docs/dev/how_to/bumping_minor_or_major_versions.md
+++ b/docs/dev/how_to/bumping_minor_or_major_versions.md
@@ -2,14 +2,15 @@
 
 ## When to Bump Versions
 
-
 After performing the monthly minor release of Chef, we should wait several days, and then bump the version for the next month's release. Why wait? We don't want to bump the version until we are sure we do not need to perform an emergency release for a regression. Once we're fairly confident we won't be performing a regression release, we want all new builds for the current channel to have the next month's version. This makes it very clear what version of Chef users are testing within the current channel.
 
 Bumping for the yearly major release is a bit different. We can bump for the new major release once we create a stable branch for the current major version number. Once this branch and version bump occurs, all development on master will be for the upcoming major release, and anything going into the stable release will need to be backported. See [Branching and Backporting](branching_and_backporting.md) for more information on how we branch and backport to stable.
 
+See [Bumping The Major Version](bumping_the_major_version.md) for the major version bump process.
+
 ### How to Bump
 
 Chef's Expeditor tool includes functionality to bump the minor or major version of the product. By using Expeditor to bump versions, we can perform a bump without directly editing the version files. A version bump is performed when a PR is merged with either of these two labels applied:
- - Expeditor: Bump Version Minor
- - Expeditor: Bump Version Major
 
+- Expeditor: Bump Version Minor
+- Expeditor: Bump Version Major
diff --git a/docs/dev/how_to/bumping_the_major_version.md b/docs/dev/how_to/bumping_the_major_version.md
new file mode 100644
index 0000000000..446b927217
--- /dev/null
+++ b/docs/dev/how_to/bumping_the_major_version.md
@@ -0,0 +1,50 @@
+# Bumping Major Version Number
+
+This document outlines the process for bumping the major version of Chef Infra Client for the yearly release.
+
+## Preparing Ohai
+
+Chef consumes Ohai from GitHub as both a runtime dependency and a testing dependency for Test Kitchen validations in Buildkite. Ohai's version is tightly coupled to that of Chef Infra Client so the first step in bumping the major release in the chef/chef repo is to bump the major version of Ohai.
+
+### Create a new stable branch of Ohai
+
+On your local machine fork the current master branch to a new stable branch. For example: `git checkout -b 15-stable`. You’ll then want to edit the Expeditor config.yml file to update the branch configs like this:
+
+https://github.com/chef/ohai/commit/ad208165619425dd7886b2de3f168b49ded25146
+
+With the expeditor config complete push the branch `git push --set-upstream origin 15-stable`
+
+### Bump Ohai master to the new major version
+
+Create a PR which:
+
+- Edits the `VERSION` file in the root of the repository to the new major release
+- Updates the `chef-config` dependency to allow for the new major release of Chef Infra in `ohai.gemspec`
+
+## Fork Chef master to a stable branch
+
+Before bumping the major version of Chef Infra we want to fork off the current master to a new stable branch, which will be used to build hotfix releases. We support the N-1 version of Chef Infra Client for a year after the release of a new major version. For example Chef Infra Client 16 was released in April 2020, at which point Chef Infra Client 15 became the N-1 release. Chef Infra Client 15 will then be maintained with critical bug and security fixes until April 2021.
+
+On your local machine fork the current master branch to a new stable branch. For example: `git checkout -b chef-15` and `git push --set-upstream origin chef-15`, which can then be pushed up to GitHub.
+
+### Create a branch to fixup your new stable branch for release
+
+Once you’ve forked to a new stable branch such as `chef-15` you’ll want to create a new branch so you can build a PR, which will get this branch ready for release:
+
+- In ./expeditor/config.yml add the version_constraint for the new branch, update the version_constrant for master to match the new major version, and remove all the update_dep.sh subscriptions which don’t work against stable branches.
+- In readme.md update the buildkite badge to point to the new stable branch image and link instead of pointing to master.
+- In kitchen-tests/Gemfile update the Ohai branch to point to the new Ohai stable
+- In kitchen-tests/kitchen.yml update chef_version to be your new stable version and not current. Ex: 15
+- In Gemfile set ohai to pull from the ohai stable branch
+- Run `rake dependencies:update`
+
+Example PR for Chef 15: https://github.com/chef/chef/pull/9236
+
+## Bump master for the new major release
+
+Create a PR that performs the following:
+
+- Update the version in the VERSION file
+- Update chef.gemspec to point to the new ohai major release
+- Update .expeditor/config.yml to include the new version_constraints you setup on your stable branch and an updated project alias
+- run `rake dependencies:update`
diff --git a/docs/dev/how_to/releasing_chef_infra.md b/docs/dev/how_to/releasing_chef_infra.md
index 8ff2165351..68070c420b 100644
--- a/docs/dev/how_to/releasing_chef_infra.md
+++ b/docs/dev/how_to/releasing_chef_infra.md
@@ -58,6 +58,7 @@ Many of our users consume Chef via Homebrew using our casks. Expeditor will crea
 Many Windows users consume our packages via Chocolatey. Make sure to update the various version strings and sha checksums here: https://github.com/chef/chocolatey-packages
 
 Once this is updated, you'll need to build / push the artifact to the Chocolatey site from a Windows host:
+
   1. `choco pack .\chef-client\chef-client.nuspec`
   2. `choco push .\chef-client.15.1.9.nupkg --key API_KEY_HERE`