Add documentation

.editorconfig

@@ -7,3 +7,6 @@ end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
+
+[*.md]
+max_line_length = unset

README.md

@@ -4,11 +4,11 @@ This is an interactive command-line tool that automates steps involved in prepar
 
 ## Installation
 
-TODO
+This tool is intended to be run as a global executable, so it does not require installation in any project.
 
 ## Usage
 
-TODO
+For more on how to use this tool, please see the [docs](./docs).
 
 ## Contributing
 

docs/README.md

@@ -0,0 +1,9 @@
+# Documentation
+
+This directory holds a collection of guides that explain what role this tool plays in the release process and how to use it for different kinds of projects. It's recommended you go through these in order if you're new to this tool:
+
+- [Understanding your project](./understanding.md)
+- [Setting up your project](./setup.md)
+- [Calling the executable](./calling.md)
+- [Using this tool](./usage.md)
+- [Addendum: Maintaining the changelog](./changelog.md)

docs/calling.md

@@ -0,0 +1,15 @@
+# Calling the executable
+
+The name of the executable that this tool exports is called `create-release-branch`. However, you will rarely use this directly. Instead, you'll use one of two wrappers depending on which package manager you are using for your project. For Yarn v1 and NPM, you'll want to use `npx`, e.g.:
+
+```
+npx @metamask/create-release-branch [OPTIONS]
+```
+
+Whereas for Yarn v2 and above, you'll want to use `yarn dlx`, e.g.:
+
+```
+yarn dlx @metamask/create-release-branch [OPTIONS]
+```
+
+In other guides, this is shortened to `create-release-branch`, but you will want to keep the full command in mind.

docs/changelog.md

@@ -0,0 +1,15 @@
+# Addendum: Maintaining the changelog
+
+We use [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) as a guide for writing changelogs. To summarize, however, the goal of a changelog is to document the noteworthy changes that have been made to the project. Although this tool provides some automation around keeping changelogs up to date, they are designed to be maintained by hand.
+
+After running this tool, you'll want to follow a few steps:
+
+1. First, you'll want to ensure that each change entry has been placed into an appropriate change category (see [here](https://keepachangelog.com/en/1.0.0/#types) for the full list of change categories as well as the correct ordering).
+
+2. Next, you'll want to curate the entries in each category. This could mean:
+
+   - **Rewording/rephrasing.** The changelog should be understandable by anyone who wants to use your project, regardless of their experience. Although references to modules/interfaces may be necessary, prefer abstract and non-technical language over jargon.
+   - **Consolidation.** A changelog entry represents a complete unit of work, and some work may be split across multiple commits. In this case, you can combine multiple entries together, listing multiple PRs instead of just one.
+   - **Omission.** Some changes do not affect end users of the project (e.g. lockfile changes, development environment changes, etc.). In these cases, you may remove these entries entirely. Exceptions may be made for changes that might be of interest despite not having an effect upon the published package (e.g. major test improvements, security improvements, improved documentation, etc.).
+
+3. Once you're made your edits, make sure to run `yarn auto-changelog validate --rc` to check that the changelog is correctly formatted.

docs/setup.md

@@ -0,0 +1,45 @@
+# Setting up your project
+
+There are three different use cases that this tool supports: polyrepos, monorepos with fixed versions, and monorepos with independent versions (see [here](./understanding.md) for more about the implications between them). The tool has the ability to detect the difference between these at runtime, provided that some requirements are met.
+
+## Polyrepos
+
+First, by default, the tool will assume your project is a polyrepo, so if that is the case, you can start using the tool right away — no setup needed.
+
+## Monorepos
+
+To determine whether a project is a monorepo, the tool looks for the existence of a non-empty `workspaces` field within the project's `package.json` file. In other words, it assumes that you are using workspaces to manage the packages within a repo. Likely you are already doing this for your monorepo, but if not, then you will want to adopt this feature (which is supported by all package managers) and add this field.
+
+Additionally, to determine which versioning strategy a monorepo uses, you will
+need to provide some configuration. The tool will look for the presence of a `@metamask/create-release-branch` section in the root package's `package.json` for options, and one of the options supported is `versioningStrategy`. The expected value for this option and associated requirements are explained below.
+
+### Monorepos with fixed versions
+
+For a monorepo with fixed versions, you will update the root `package.json` with a `versioningStrategy` of `"fixed"`. For example:
+
+```json
+{
+  "version": "1.0.0",
+  "workspaces": ["packages/*"],
+  "@metamask/create-release-branch": {
+    "versioningStrategy": "fixed"
+  }
+}
+```
+
+### Monorepos with independent versions
+
+For a monorepo with independent versions, you will want to make two changes to the root `package.json`:
+
+1. Use a `versioningStrategy` of `"independent"`
+2. Change the format of the `version` from `<major>.<minor>.<patch>` to `<year>.<month>.<day>-<build number>` ("1" is a sensible starting build number). For example:
+
+```json
+{
+  "version": "2022.6.7-1",
+  "workspaces": ["packages/*"],
+  "@metamask/create-release-branch": {
+    "versioningStrategy": "independent"
+  }
+}
+```

docs/understanding.md

@@ -0,0 +1,27 @@
+# Understanding your project
+
+Before you use this tool, you'll want to ask three questions:
+
+1. Which version of Yarn is my project using: "classic" Yarn (v1) or "modern" Yarn (v2 and beyond)?
+2. Is my project a polyrepo or a monorepo?
+3. If my project is a monorepo, am I using a fixed versioning strategy or an independent versioning strategy?
+
+The answers to these questions impact how you use this tool.
+
+## Package manager
+
+There are many differences between Yarn 1.x and 2.x (and all versions after it). One of these changes concerns how to run executables in globally available packages. You can read more about that [here](./calling.md).
+
+## Role
+
+Your project may be a _polyrepo_, housing only one NPM package, or a _monorepo_, housing multiple NPM packages. The nature of your project changes the workflow behind this tool, as the process involved in preparing a release for a monorepo is more complex than for a polyrepo, as the tool needs to discover and operate on files within multiple directories within your project instead of just one, and it cannot make the same assumptions about which files to update as it can for a polyrepo.
+
+## Versioning strategy (monorepo only)
+
+Finally, if your project is a monorepo, there are a couple of different ways that you can maintain versions across your packages.
+
+If you are following a _fixed_ versioning strategy, it means that your monorepo has a top-level version, and when you issue a new release, you will update this version along with any packages you want to include in the release to the same version.
+
+If you are following an _independent_ versioning strategy, your monorepo has no such top-level version, so when you issue a new release, you do not need to synchronize the versions of packages you want to include in the release.
+
+The independent strategy is slightly more complex than the fixed strategy, as in the fixed strategy, you need to specify only one release version, whereas in the independent case, you need to specify versions for one or many packages.

docs/usage-monorepo-fixed.md

@@ -0,0 +1,28 @@
+# Using the tool for a monorepo with fixed versions
+
+For a monorepo with fixed versions, the tool needs to know not only which version you want to release, but also which packages you want to release.
+
+Start by running:
+
+```
+create-release-branch
+```
+
+The tool will generate a YAML file format and open it in your editor (or, if it cannot detect an appropriate editor, give you the path to the file for you to open yourself). This file contains two fields:
+
+- **`releaseVersion`:** Specifies the new version that you want to release. This can either be:
+  - `major` if you want to bump the major part of the current version. For instance, if the current version is 1.0.0, then the release version would be 2.0.0.
+  - `minor` if you want to bump the minor part of the current version. For instance, if the current version is 1.0.0, then the release version would be 1.1.0.
+  - `patch` if you want to bump the patch part of the current version. For instance, if the current version is 1.0.0, then the release version would be 1.0.1.
+  - An exact version such as `1.2.3`.
+- **`packages`:** An array that lists the names of workspace packages that you want to release. The versions of the packages provided here will be changed to the `releaseVersion`. This list will be populated with all of the packages that have any changed since the previous release, but you are free to remove or add any line as long as it refers to a valid workspace package.
+
+Once you've filled out this file, save and close it, and the tool will continue. (Or, if the tool couldn't detect your editor and you had to edit the file manually, then run `create-release-branch --continue`.)
+
+At this point, the tool will:
+
+1. Adjust the `version` of the root package, and all of the provided packages, to the version specified.
+2. Go through each workspace package specified, and:
+   1. Read the Git history of the repo to extract the names of the commits which have made any changes to any files within the package since the Git tag that corresponds to the current version of the package.
+   2. Add a new section to the changelog for the package which is titled by the release version and which lists the commits gathered.
+3. Commit the changes to a new branch called `release/<release-version>` (e.g. `release/1.2.3`) and switch to that branch.

docs/usage-monorepo-independent.md

@@ -0,0 +1,40 @@
+# Using the tool for a monorepo with independent versions
+
+For a monorepo with independent versions, the tool needs to know which packages you want to release and how to set the version for each package.
+
+Start by running:
+
+```
+create-release-branch
+```
+
+The tool will generate a YAML file format and open it in your editor (or, if it cannot detect an appropriate editor, give you the path to the file for you to open yourself). This file contains one field, `packages`, which is an object where:
+
+- Each key is the name of the workspace package you want to release.
+- Each value specifies the new version the package should receive. This can either be:
+  - `major` if you want to bump the major part of the current version. For instance, if the current version is 1.0.0, then the release version would be 2.0.0.
+  - `minor` if you want to bump the minor part of the current version. For instance, if the current version is 1.0.0, then the release version would be 1.1.0.
+  - `patch` if you want to bump the patch part of the current version. For instance, if the current version is 1.0.0, then the release version would be 1.0.1.
+  - An exact version such as `1.2.3`.
+
+This object will be populated with all of the packages that have any changed since the previous release, but you are free to remove or add any line as long as it refers to a valid workspace package.
+
+Here is an example:
+
+```
+@metamask/base-controller: major
+@metamask/controller-utils: minor
+@metamask/transaction-controller: patch
+@metamask/assets-controllers: 1.6.3
+```
+
+Once you've filled out this file, save and close it, and the tool will continue. (Or, if the tool couldn't detect your editor and you had to edit the file manually, then run `create-release-branch --continue`).
+
+At this point, the tool will:
+
+1. Calculate a new release version by extracting the build number from the current version, incrementing it, and combining it with the current date, then setting the `version` of the root package to this new version.
+2. Go through each workspace package specified, and:
+   1. Adjust the `version` of the package to the version specified.
+   2. Read the Git history of the repo to extract the names of the commits which have made any changes to any files within the package since the Git tag that corresponds to the current version of the package.
+   3. Add a new section to the changelog for the package which is titled by the release version and which lists the commits gathered.
+3. Commit the changes to a new branch called `release/<release-version>`, where `<release-version>` is the version calculated in step one (e.g. `release/2022.6.8-123`), and switch to that branch.

docs/usage-polyrepo.md

@@ -0,0 +1,39 @@
+# Using the tool for a polyrepo
+
+For a polyrepo, the tool needs to know the new version of the package that you want to release (hereafter called the "release version"). This can happen one of two ways:
+
+1. You can have the tool determine the release version automatically by bumping the major, minor, or patch part of the current version.
+
+   For instance, if the current version is 1.0.0, then this command would bump the version to 2.0.0:
+
+   ```
+   create-release-branch --bump major
+   ```
+
+   If the current version is 1.0.0, then this command would bump the version to 1.1.0:
+
+   ```
+   create-release-branch --bump minor
+   ```
+
+   If the current version is 1.0.0, then this command would bump the version to 1.0.1:
+
+   ```
+   create-release-branch --bump patch
+   ```
+
+2. You can provide the version exactly. For instance, this command would change the version to 1.2.3 regardless of the current version:
+
+   ```
+   create-release-branch --version 1.2.3
+   ```
+
+After you run the command, the tool will:
+
+1. Adjust the version of the package to the version specified.
+2. Read the Git history of the repo to extract the names of the commits which have occurred since the Git tag that corresponds to the current version (before being changed).
+3. Add a new section to the changelog for the release version which lists the commits gathered.
+4. Commit the changes to a new branch called `release/<release-version>` (e.g. `release/1.2.3`) and switch to that branch.
+
+At this point, you'll need to revise the changelog to place the newly added entries within the appropriate categories and to edit them to be more easily understood by users of the project.
+Read [this guide](./changelog.md) for more on how to do this.

docs/usage.md

@@ -0,0 +1,7 @@
+# Using this tool
+
+The tool follows a slightly different workflow depending on what kind of project you have:
+
+- [Polyrepo](./usage-polyrepo.md)
+- [Monorepo with fixed versions](./usage-monorepo-fixed.md)
+- [Monorepo with independent versions](./usage-monorepo-independent.md)

docs/workflow.md

@@ -0,0 +1,7 @@
+# Using this tool
+
+From here, the road splits into three, depending on your use case:
+
+- [Polyrepo](./usage-polyrepo.md)
+- [Monorepo with fixed versions](./usage-monorepo-fixed.md)
+- [Monorepo with independent versions](./usage-monorepo-independent.md)