Updating CONTRIBUTING.md and how to release (#13484)

to specifically call out some merging and branching practices as well as troubleshooting of release and order of operations.

Signed-off-by: Thomas Powell <powell@progress.com>

3 files changed, 20 insertions, 2 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 16e675929e..7afa62f74f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,12 +20,18 @@ We have a 3 step process for contributions:
 2. Create a GitHub Pull Request for your change, following the instructions in the pull request template.
 3. Perform a [Code Review](#code-review-process) with the project maintainers on the pull request.
 
+### Branching
+
+* If branching within `chef/chef` repo, prefix your initials such as `tp/branch-name` to help delineate at a glance who created the branch.
+* (for internal teams) Please include a ticket number for JIRA (e.g., `tp/infc-399-branch-short-desc`) if possible to help JIRA link back to the branch and subsequent PR.
+
 ### Pull Request Requirements
 
 Chef Projects are built to last. We strive to ensure high quality throughout the experience. In order to ensure this, we require that all pull requests to Chef projects meet these specifications:
 
 1. **Tests:** To ensure high quality code and protect against future regressions, we require all the code in Chef Projects to have at least unit test coverage. We use [RSpec](http://rspec.info/) for unit testing.
 2. **Green CI Tests:** We use [Buildkite](https://buildkite.com/chef-oss) to test all pull requests. We require these test runs to succeed on every pull request before being merged.
+3. **Rebase** `git rebase {target-branch}` prior to merging. :no_entry: Avoid pulling in the target branch, as mixing and matching with `rebase` can easily make a mess of the commit history :sob:... You will likely need to `git push -f {remote-branch}` after rebasing.
 
 ### Code Review Process
 
@@ -121,6 +127,10 @@ Date:   Wed Sep 18 11:44:40 2015 -0700
 ------------------------------------------------------------------------
 ```
 
+### Merging
+1. Use `[Squash and Merge]` and edit down the commit history to a clear description of what the changes were with the "TL;DR" bits in the first 60 characters of the commit message. Update the PR title if necessary.
+2. Add the changes to the [Pending Release Notes](https://github.com/chef/chef/wiki) for the appropriate release version.
+
 ## Release Cycles
 
 Our primary shipping vehicle is operating system specific packages that includes all the requirements of Chef. The packages are built with our [Omnibus](https://github.com/chef/omnibus) packing project.
diff --git a/cspell.json b/cspell.json
index 497e5e09ba..0a504ef1cc 100644
--- a/cspell.json
+++ b/cspell.json
@@ -541,6 +541,7 @@
     "indentable",
     "INET",
     "inet",
+    "infc",
     "INFLOOP",
     "iniparse",
     "Inout",
diff --git a/docs/dev/how_to/releasing_chef_infra.md b/docs/dev/how_to/releasing_chef_infra.md
index f15e5d634c..991357cc65 100644
--- a/docs/dev/how_to/releasing_chef_infra.md
+++ b/docs/dev/how_to/releasing_chef_infra.md
@@ -28,23 +28,26 @@ The importance of our release notes cannot be understated. As developers, we und
 
 If there are any new or updated resources, the docs site will need to be updated. This is a `partially` automated process. If you are making a single resource update or changing wording, it may just be easier to do it by hand.
 
+`publish-release-notes.sh` pushes to S3 and then Netlify site needs to be rebuilt, so the Docs Site may not immediately reflect the Release notes related updates. The way to rebuild Netlify is manually or by merging a PR in chef-web-docs repository. Reach out to the Docs team to trigger an update.
+
 #### Resource Documentation Automation
 
 1. Run `rake docs_site:resources` to generate content to a `docs_site` directory
    1. WARNING: Any resource that inherits it's basic structure from a parent resource is likely to commingle settings from both when you run that command. For example, there are 17-20 resources that consume the basic package.rb resource file. As a consequence, ALL of the children will most likely have pulled in properties and actions that do not apply to them. You have to be careful here.
 
 2. Compare the relevant generated files to the content in the `content/resources` directory within the [chef-web-docs repo](https://github.com/chef/chef-web-docs/). The generated files are missing some content, such as action descriptions, and don't have perfect formatting, so this is a bit of an art form.
-   1. This will take time - expect to use 2-4 days of going through the new docs to ensure you aren't accidentally overwriting things or ignoring important updates
+   1. This will take time - expect to use 2-4 days of going through the new docs to ensure you aren't accidentally overwriting things or ignoring important updates.
    2. One tool you can use to help yourself is Beyond Compare. If you have to buy it, it's like $20
    3. You'll end up using a combo of the old docs, the new docs, what Beyond Compare shows you and your intuition.
 
-
 ## Release Chef Infra Client
 
 The docs are the most time-consuming aspect of the release.
 
 ### Promote the build
 
+:warning: Be sure to update the appropriate version of Pending Release Notes in the [wiki](https://github.com/chef/chef/wiki)! Failure to do so will cause the `git commit` step in [`publish-release-notes.sh`](https://github.com/chef/chef/blob/main/.expeditor/publish-release-notes.sh#L30) to fail.
+
 Chef employees can promote a build to stable from Slack. This is done with expeditor using a chatops command in the following format:
 
 `/expeditor promote chef/chef:main 17.1.9`
@@ -53,6 +56,10 @@ or for a previous release branch:
 
 `/expeditor promote chef/chef:chef-16 16.13.9`
 
+:warning: Do not `gem push` the ruby gem manually... this will prevent promotion of habitat packages to stable and will block notifications to chef.io slack channels.
+
+:information_source: the promotion of habitat packages can also be blocked if the Linux and Linux2 packages somehow have the same timestamp.
+
 ### Announce the Build
 
 Also, make sure to announce the build on any social media platforms that you occupy if you feel comfortable doing so. It's great to make an announcement in `#sous-chefs` and `#general` in Community Slack, where we tend to get a good response.