Merge pull request #798 from alphagov/document-unreleased-readme-impo…

…rtance

Add CHANGELOG_TEMPLATE to make changelogs easier for new contributors

CHANGELOG.md

@@ -4,13 +4,31 @@ Note: We're not following semantic versioning yet, we are going to talk about th
 
 ## Unreleased
 
+💥 Breaking changes:
+
+- Pull Request Title goes here
+
+  Description goes here (optional)
+
+  To migrate you need to change: X
+
+  ([PR #N](https://github.com/alphagov/govuk-frontend/pull/N))
+
 🆕 New features:
 
 - Add default text for back-link component
   ([PR #793](https://github.com/alphagov/govuk-frontend/pull/793))
 - Add default container class to the header component
   ([PR #807](https://github.com/alphagov/govuk-frontend/pull/807))
 
+🔧 Fixes:
+
+- Pull Request Title goes here
+
+  Description goes here (optional)
+
+  ([PR #N](https://github.com/alphagov/govuk-frontend/pull/N))
+
 🏠 Internal:
 
 - Remove instructions to login with npm, which is no longer required
@@ -28,6 +46,8 @@ Note: We're not following semantic versioning yet, we are going to talk about th
 - Add notice about the use of `html` arguments in Nunjucks macros for production
   ([PR #785](https://github.com/alphagov/govuk-frontend/pull/785))
 
+- Add CHANGELOG_TEMPLATE to make changelogs easier for new contributors
+  ([PR #798](https://github.com/alphagov/govuk-frontend/pull/798))
 
 ## 0.0.32 (Breaking release)
 

CONTRIBUTING.md

@@ -73,9 +73,16 @@ which describes how we prefer git history and commit messages to read.
 
 If you open a GitHub pull request on this repo, please update `CHANGELOG` to reflect your contribution.
 
-Add your entry under `Unreleased` as `Breaking change`, `New feature`, `Fix` or `Internal`.
+Add your entry under `Unreleased` as `Breaking changes`, `New features`, `Fixes` or `Internal`.
 
-Please include a description of the work done and a link to the PR (see current `CHANGELOG` for the format).
+These sections follow [semantic versioning](https://semver.org/), where:
+
+- `Breaking changes` corresponds to a `major` (1.X.X) change.
+- `New features` corresponds to a `minor` (X.1.X) change.
+- `Fixes` corresponds to a `patch` (X.X.1) change.
+- `Internal` corresponds to changes to the project that are not part of the public API, for example fixing the CI build server.
+
+See the [`CHANGELOG_TEMPLATE.md`](/docs/contribution/CHANGELOG_TEMPLATE.md) for an example for how this looks.
 
 Include the modified `CHANGELOG` in the PR.
 

docs/contributing/CHANGELOG_TEMPLATE.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## Unreleased
+
+💥 Breaking changes:
+
+- Pull Request Title goes here
+
+  Description goes here (optional)
+
+  To migrate you need to change: X
+
+  ([PR #N](https://github.com/alphagov/govuk-frontend/pull/N))
+
+🆕 New features:
+
+- Pull Request Title goes here
+
+  Description goes here (optional)
+
+  ([PR #N](https://github.com/alphagov/govuk-frontend/pull/N))
+
+🔧 Fixes:
+
+- Pull Request Title goes here
+
+  Description goes here (optional)
+
+  ([PR #N](https://github.com/alphagov/govuk-frontend/pull/N))
+
+🏠 Internal:
+
+- Pull Request Title goes here
+
+  Description goes here (optional)
+
+  ([PR #N](https://github.com/alphagov/govuk-frontend/pull/N))

docs/contributing/publishing.md

@@ -11,6 +11,8 @@
 5. Update [`CHANGELOG.md`](../../CHANGELOG.md) "Unreleased" heading with the new version number.
    This should be incremented based on [Semantic versioning](https://semver.org/) from the unreleased changes listed.
 
+  Copy the [`CHANGELOG_TEMPLATE.md`](./CHANGELOG_TEMPLATE.md), above the new release to make it easy for new contributors.
+
 6. Update [`package/package.json`](../../package/package.json) version with the new version number.
 This should be incremented based on [Semantic versioning](https://semver.org/) from the unreleased changes listed.