Skip to content

Commit

Permalink
change: [M3-8418] - Add documentation on changeset best practices (li…
Browse files Browse the repository at this point in the history
…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
  • Loading branch information
mjac0bs authored Aug 7, 2024
1 parent b383ea9 commit db33a8d
Showing 6 changed files with 24 additions and 5 deletions.
16 changes: 15 additions & 1 deletion docs/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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`.
2 changes: 1 addition & 1 deletion docs/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion packages/api-v4/.changeset/README.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion packages/manager/.changeset/README.md
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 5 additions & 0 deletions packages/manager/.changeset/pr-10758-added-1722975143465.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@linode/manager": Added
---

Documentation for changeset best practices ([#10758](https://github.com/linode/manager/pull/10758))
2 changes: 1 addition & 1 deletion packages/validation/.changeset/README.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit db33a8d

Please sign in to comment.