From 888b9704988a687b3831c9aff17016adc3a49ef7 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Thu, 7 Oct 2021 14:48:25 +0200 Subject: [PATCH 1/4] Add docs for writing changesets Signed-off-by: Johan Haals --- CONTRIBUTING.md | 7 ++- docs/getting-started/contributors.md | 85 ++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5242309eee..ad17ff17f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md index e12c0c5f17..9af57277d9 100644 --- a/docs/getting-started/contributors.md +++ b/docs/getting-started/contributors.md @@ -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, + }); +``` From c3b29843b2b5452ea9642d638bbaf3490637a3cb Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Thu, 7 Oct 2021 16:23:06 +0200 Subject: [PATCH 2/4] Update docs/getting-started/contributors.md Signed-off-by: Johan Haals Co-authored-by: Adam Harvey --- docs/getting-started/contributors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md index 9af57277d9..7b612ccd0d 100644 --- a/docs/getting-started/contributors.md +++ b/docs/getting-started/contributors.md @@ -193,7 +193,7 @@ getEntity is now a function that returns a Promise. **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 +### Changes to code should include a diff of the files that need updating #### Bad From 4130394b7943eea1291d555c31b3e38e751b7821 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Fri, 8 Oct 2021 15:09:30 +0200 Subject: [PATCH 3/4] Update link wording Signed-off-by: Johan Haals --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad17ff17f9..99d63cf0b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -129,7 +129,7 @@ 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. 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). +4. Explain your changes in the generated changeset. See [examples of well written changesets](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 From d0dba0a448f4ad23928e09b018f1fa7e41787e7a Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Mon, 11 Oct 2021 11:26:49 +0200 Subject: [PATCH 4/4] place example in indented code block Signed-off-by: Johan Haals --- docs/getting-started/contributors.md | 34 ++++++++++++++++------------ 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md index 7b612ccd0d..ed56d63cab 100644 --- a/docs/getting-started/contributors.md +++ b/docs/getting-started/contributors.md @@ -207,20 +207,24 @@ getEntity is now a function that returns a Promise. #### Good -**BREAKING** The catalog createRouter now requires that a `FluxCapacitor` is -passed to the router. + --- + '@backstage/catalog': patch + --- -These changes are **required** to `packages/backend/src/plugins/catalog.ts` + **BREAKING** The catalog createRouter now requires that a `FluxCapacitor` is + passed to the router. -```diff -+ import { FluxCapacitor } from '@backstage/time'; -+ const fluxCapacitor = new FluxCapacitor(); - return await createRouter({ - entitiesCatalog, - locationAnalyzer, - locationService, -+ fluxCapacitor, - logger: env.logger, - config: env.config, - }); -``` + 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, + }); + ```