Add instructions for manual CHANGELOG fixups
@@ -211,6 +211,33 @@ make template_reference
Verify the diff looks reasonable and matches the newly released version, then submit your PR.
+## Update the Changelog
+
+We currently use Expeditor (an internal tool) to _partially_ manage our changelog. It adds items to `CHANGELOG.md` for every PR that is merged, based on certain labels that are attached to the PR. This is all well and good.
+
+However, due to our versioning scheme (specifically, the use of the `-dev` suffix), we can't yet take advantage of Expeditor's built-in version bumping capabilities. This will change soon, but in the meantime, this means that we must manually add the release header to the changelog and do some re-arranging of additional headers.
+
+In a nutshell, the top of the `CHANGELOG.md` file should be modified to look something like this:
+
+```
+# Habitat CHANGELOG
+
+<!-- latest_release unreleased -->
+
+## Unreleased
+
+// Any merges after the release tag should be in this section
+
+<!-- latest_release -->
+
+## [<JUST_RELEASED_VERSION>](https://github.com/habitat-sh/habitat/tree/<JUST_RELEASED_VERSION>) (YYYY-MM-DD)
+[Full Changelog](https://github.com/habitat-sh/habitat/compare/LAST_VERSION...<JUST_RELEASED_VERSION>)
+```
+
+These are the only places in the file that the `latest_release unreleased` and `latest_release` comment lines should be.
+
+For additional background, please consult [Expeditor's CHANGELOG documentation](https://expeditor.chef.io/docs/reference/changelog/).
+
# Drink. It. In.
## Bump Version
