Add towncrier configuration

towncrier is a utility to produce useful, summarized news files (also
known as changelogs) for your project [1]. It provides us with the
ability for contributor to write their own meaningful additions to
the changelog without risking continuous merge conflicts.

This should be used for v2. v1 can continue to use the legacy method.

[1] https://pypi.org/project/towncrier/

Signed-off-by: Stephen Finucane <stephenfin@redhat.com>

RELEASE.md

@@ -7,6 +7,7 @@
 Gophercloud follows [semver](https://semver.org/).
 
 Each Pull request must have a label indicating its impact on the API:
+
 * `semver:patch` for changes that don't impact the API
 * `semver:minor` for changes that impact the API in a backwards-compatible fashion
 * `semver:major` for changes that introduce a breaking change in the API
@@ -15,12 +16,12 @@ Automation prevents merges if the label is not present.
 
 ### Metadata
 
-The release notes for a given release are generated based on the PR title: make
-sure that the PR title is descriptive.
+The release notes for a given release are generated based on the PR title: make sure that the PR title is descriptive.
 
 ## Release of a new version
 
 Requirements:
+
 * [`gh`](https://github.com/cli/cli)
 * [`jq`](https://stedolan.github.io/jq/)
 
@@ -30,7 +31,7 @@ Supposing that the base release is `v1.2.0`:
 
 ```
 for commit_sha in $(git log --pretty=format:"%h" v1.2.0..HEAD); do
- gh pr list --search "$commit_sha" --state merged --json number,title,labels,url
+ gh pr list --search "$commit_sha" --state merged --json number,title,labels,url
 done | jq '.[]' | jq --slurp 'unique_by(.number)' > prs.json
 ```
 
@@ -58,16 +59,16 @@ The highest semver descriptor determines the release bump.
 Once all PRs have a sensible title, generate the release notes:
 
 ```shell
-jq -r '.[] | "* [GH-\(.number)](\(.url)) \(.title)"' prs.json
+towncrier build --version 1.3.0 # update to use the correct new version
 ```
 
-Add that to the top of `CHANGELOG.md`. Also add any information that could be useful to consumers willing to upgrade.
+This will be added to `CHANGELOG.md`. You may wish to add any information that could be useful to consumers willing to upgrade.
 
-**Set the new version string in the `DefaultUserAgent` constant in `provider_client.go`.**
+## Step 4: Set the new version string in the `DefaultUserAgent` constant in `provider_client.go`.
 
 Create a PR with these two changes. The new PR should be labeled with the semver label corresponding to the type of bump.
 
-### Step 3: Git tag and Github release
+### Step 5: Git tag and Github release
 
 The Go mod system relies on Git tags. In order to simulate a review mechanism, we rely on Github to create the tag through the Release mechanism.
 
@@ -76,4 +77,5 @@ The Go mod system relies on Git tags. In order to simulate a review mechanism, w
 * Click on **Save draft**
 * Ask another Gophercloud maintainer to review and publish the release
 
-_Note: never change a release or force-push a tag. Tags are almost immediately picked up by the Go proxy and changing the commit it points to will be detected as tampering._
+> **Note**
+> Never change a release or force-push a tag. Tags are almost immediately picked up by the Go proxy and changing the commit it points to will be detected as tampering.

docs/contributor-tutorial/step-05-pull-requests.md

@@ -1,5 +1,4 @@
-Step 5: Writing the Code
-========================
+# Step 5: Writing the Code
 
 At this point, you should have:
 
@@ -20,8 +19,7 @@ to be implementing something that hasn't already been done.
 Use the existing packages as templates and mirror the style, naming, and
 logic.
 
-Types of Pull Requests
-----------------------
+## Types of Pull Requests
 
 The amount of changes you plan to make will determine how much code you should
 submit as Pull Requests.
@@ -73,15 +71,15 @@ implementing multiple API suites.
 An example of this can be seen from the Pull Requests referenced in
 [#723](https://github.com/gophercloud/gophercloud/issues/723).
 
-What to Include in a Pull Request
----------------------------------
+## What to Include in a Pull Request
 
 Each Pull Request should contain the following:
 
 1. The actual Go code to implement the feature or bug fix
 2. Unit tests
 3. Acceptance tests
 4. Documentation
+5. Release note
 
 Whether you want to bundle all of the above into a single commit or multiple
 commits is up to you. Use your preferred style.
@@ -108,8 +106,43 @@ sure to document all fields, functions, and methods appropriately. In addition,
 each package has a `doc.go` file which should be created or amended with
 details of your Pull Request, where appropriate.
 
-Dealing with Related Pull Requests
-----------------------------------
+### Release note
+
+Release notes are handled via [towncrier](https://towncrier.readthedocs.io/).
+This allows you to create a news fragment. `towncrier` can be installed like
+any of other Python executable, using tools like `pip`, `pipx`, or your
+distro's package manager if on Linux. For example, using `pipx`:
+
+```shell
+pipx install towncrier
+```
+
+Once installed, release notes can be created using the `towncrier create`
+command. This expects a single argument, `FILENAME`, which should be either an
+issue number or a random string prefixed with `+`, followed by a category. The
+available categories can be seen by using `towncrier create --help`.
+
+For example, if you are addressing a feature request, reported as issue #1234,
+run:
+
+```shell
+towncrier create 1234.feature
+```
+
+For example, if you are adding a minor feature that doesn't warrant an issue,
+run:
+
+```shell
+towncrier create +add-tiny-feature.feature
+```
+
+> *Note*
+> Bugfixes should always have an issue.
+
+In all cases, a news fragment will be created in the `news` directory. These
+fragments will be squashed into the `CHANGELOG.md` file when releasing.
+
+## Dealing with Related Pull Requests
 
 If you plan to open more than one Pull Request, it's only natural that code
 from one Pull Request will be dependent on code from the prior Pull Request.

towncrier.toml

@@ -0,0 +1,23 @@
+# Configuration for towncrier
+#
+# https://towncrier.readthedocs.io/en/stable/configuration.html
+[tool.towncrier]
+name = "Gophercloud"
+filename = "CHANGELOG.md"
+directory = "news"
+
+[[tool.towncrier.type]]
+directory = "upgrade"
+name = "Upgrade notes"
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "New features and improvements"
+
+[[tool.towncrier.type]]
+directory = "fix"
+name = "Bugfixes"
+
+[[tool.towncrier.type]]
+directory = "ci"
+name = "CI changes"