change: [M3-8418] - Add documentation on changeset best practices (li…

…node#10758)

* Add changeset best practices

* Clean up

* Added changeset: Documentation for changeset best practices

* Add changesets

* Address feedback: reduce duplication and include in CONTRIBUTING

docs/CONTRIBUTING.md

@@ -27,7 +27,7 @@ Feel free to open an issue to report a bug or request a feature.
     **Example:** `feat: [M3-1234] - Allow user to view their login history`
 
 6. Open a pull request against `develop` and make sure the title follows the same format as the commit message.
-7. If needed, create a changeset to populate our changelog
+7. If needed, create a changeset to populate our changelog.
     - If you don't have the Github CLI installed or need to update it (you need GH CLI 2.21.0 or greater),
         - install it via `brew`: https://github.com/cli/cli#installation or upgrade with `brew upgrade gh`
         - Once installed, run `gh repo set-default` and pick `linode/manager` (only > 2.21.0)
@@ -37,9 +37,23 @@ Feel free to open an issue to report a bug or request a feature.
     - A changeset is optional, but should be included if the PR falls in one of the following categories:<br>
     `Added`, `Fixed`, `Changed`, `Removed`, `Tech Stories`, `Tests`, `Upcoming Features`
       - Select the changeset category that matches the commit type in your PR title. (Where this isn't a 1:1 match: generally, a `feat` commit type falls under an `Added` change and `refactor` falls under `Tech Stories`.)
+      - Write your changeset by following our [best practices](#writing-a-changeset).
 
 Two reviews from members of the Cloud Manager team are required before merge. After approval, all pull requests are squash merged.
 
+## Writing a changeset
+
+Follow these best practices to write a good changeset:
+
+- Use a consistent tense in all changeset entries. We have chosen to use **imperative (present)** tense. (This follows established [git commit message best practices](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).)
+- Avoid starting a changeset with the verb "Add", "Remove", "Change" or "Fix" when listed under that respective `Added`, `Removed`, `Changed` or `Fixed` section. It is unnecessary repetition.
+- For `Fixed` changesets, describe the bug that needed to be fixed, rather than the fix itself. (e.g. say "Missing button labels in action buttons" rather than "Make label prop required for action buttons").
+- Begin a changeset with a capital letter, but do not end it with a period; it's not a complete sentence.
+- When referencing code, consider adding backticks for readability. (e.g. "Update `updateImageRegions` to accept `UpdateImageRegionsPayload` instead of `regions: string[]`").
+- Use the `Upcoming Features` section for ongoing project work that is behind a feature flag. If additional changes are being made that are not feature flagged, add another changeset to describe that work.
+- Add changesets for `docs/` documentation changes in the `manager` package, as this is generally best-fit.
+- Generally, if the code change is a fix for a previous change that has been merged to `develop` but was never released to production, we don't need to include a changeset.
+
 ## Docs
 
 To run the docs development server locally, [install Bun](https://bun.sh/) and start the server: `yarn docs`.

docs/PULL_REQUEST_TEMPLATE.md

@@ -42,7 +42,7 @@ Please specify a release date to guarantee timely review of this PR. If exact da
 - [ ] 👀 Doing a self review
 - [ ] ❔ Our [contribution guidelines](https://github.com/linode/manager/blob/develop/docs/CONTRIBUTING.md)
 - [ ] 🤏 Splitting feature into small PRs
-- [ ] ➕ Adding a changeset
+- [ ] ➕ Adding a [changeset](https://github.com/linode/manager/blob/develop/docs/CONTRIBUTING.md#writing-a-changeset)
 - [ ] 🧪 Providing/Improving test coverage
 - [ ] 🔐 Removing all sensitive information from the code and PR description
 - [ ] 🚩 Using a feature flag to protect the release

packages/api-v4/.changeset/README.md

@@ -15,4 +15,4 @@ You must commit them to the repo so they can be picked up for the changelog gene
 
 This directory get wiped out when running `yarn generate-changelog`.
 
-See `changeset.mjs` for implementation details.
+See `changeset.mjs` for implementation details.

packages/manager/.changeset/README.md

@@ -15,4 +15,4 @@ You must commit them to the repo so they can be picked up for the changelog gene
 
 This directory get wiped out when running `yarn generate-changelog`.
 
-See `changeset.mjs` for implementation details.
+See `changeset.mjs` for implementation details.

packages/manager/.changeset/pr-10758-added-1722975143465.md

@@ -0,0 +1,5 @@
+---
+"@linode/manager": Added
+---
+
+Documentation for changeset best practices ([#10758](https://github.com/linode/manager/pull/10758))

packages/validation/.changeset/README.md

@@ -15,4 +15,4 @@ You must commit them to the repo so they can be picked up for the changelog gene
 
 This directory get wiped out when running `yarn generate-changelog`.
 
-See `changeset.mjs` for implementation details.
+See `changeset.mjs` for implementation details.