Add docs for writing changesets

Signed-off-by: Johan Haals <johan.haals@gmail.com>
2021-10-07 14:48:25 +02:00
parent a66ce9bb88
commit 888b970498
2 changed files with 89 additions and 3 deletions
@@ -129,9 +129,10 @@ In general, changesets are not needed for the documentation, build utilities, co
 1. Run `yarn changeset`
 2. Select which packages you want to include a changeset for
 3. Select impact of change that you're introducing, using `minor` for breaking changes and `patch` otherwise. We do not use `major` changes while packages are at version `0.x`.
-4. Add generated changeset to Git
-5. Push the commit with your changeset to the branch associated with your PR
-6. Accept our gratitude for making the release process easier on the maintainers
+4. Explain your changes in the generated changeset. Examples of a well written changeset can be found [here](https://backstage.io/docs/getting-started/contributors#writing-changesets).
+5. Add generated changeset to Git
+6. Push the commit with your changeset to the branch associated with your PR
+7. Accept our gratitude for making the release process easier on the maintainers

 For more information, checkout [adding a changeset](https://github.com/atlassian/changesets/blob/master/docs/adding-a-changeset.md) documentation in the changesets repository.

@@ -139,3 +139,88 @@ default app configs.

 You can learn more about the local configuration in
 [Static Configuration in Backstage](../conf/) section.
+
+## Writing changesets
+
+Changesets are an important part of the development process. They are used to
+generate Changelog entries for all changes to the project. Ultimately they are
+read by the end users to learn about important changes and fixes to the project.
+Some of these fixes might require manual intervention from users so it's
+important to write changesets that users understand and can take action on.
+
+Here are some important do's and don'ts when writing changesets:
+
+### Changeset should give a clear description to what has changed
+
+#### Bad
+
+```
+---
+'@backstage/catalog': patch
+---
+Fixed table layout
+```
+
+#### Good
+
+```
+---
+'@backstage/catalog': patch
+---
+
+Fixed bug in EntityTable component where table layout did not readjust properly below 1080x768 pixels.
+```
+
+### Breaking changes not caught by the type checker should be clearly marked with bold **BREAKING** text
+
+#### Bad
+
+```
+---
+'@backstage/catalog': minor
+---
+
+getEntity is now a function that returns a Promise.
+```
+
+#### Good
+
+```
+---
+'@backstage/catalog': minor
+---
+
+**BREAKING** The getEntity function now returns a Promise and **must** be awaited from now on.
+```
+
+### Changes to code should include a diff of the files that needs updating
+
+#### Bad
+
+```
+---
+'@backstage/catalog': patch
+---
+
+**BREAKING** The catalogEngine now requires a flux capacitor to be passed.
+```
+
+#### Good
+
+**BREAKING** The catalog createRouter now requires that a `FluxCapacitor` is
+passed to the router.
+
+These changes are **required** to `packages/backend/src/plugins/catalog.ts`
+
+```diff
+ import { FluxCapacitor } from '@backstage/time';
+ const fluxCapacitor = new FluxCapacitor();
+  return await createRouter({
+    entitiesCatalog,
+    locationAnalyzer,
+    locationService,
+   fluxCapacitor,
+    logger: env.logger,
+    config: env.config,
+  });
+```