Document how to create ALE releases

1 files changed, 72 insertions, 2 deletions

diff --git a/doc/ale-development.txt b/doc/ale-development.txt
index 0f06642c..946c49a1 100644
--- a/doc/ale-development.txt
+++ b/doc/ale-development.txt
@@ -15,6 +15,7 @@ CONTENTS                                             *ale-development-contents*
     4.2. Writing Fixer Tests..............|ale-development-fixer-tests|
     4.3. Running Tests in a Windows VM....|ale-development-windows-tests|
   5. Contributing.........................|ale-development-contributing|
+    5.1. Preparing a Release..............|ale-development-release|
 
 ===============================================================================
 1. Introduction                                  *ale-development-introduction*
@@ -325,7 +326,6 @@ given the above setup are as follows.
 `AssertLSPProject project_root`    - Check the root given to an LSP server.
 `AssertLSPAddress address`         - Check the address to an LSP server.
 
-
 ===============================================================================
 4.2 Writing Fixer Tests                           *ale-development-fixer-tests*
 
@@ -367,7 +367,6 @@ given the above setup are as follows.
 `AssertFixer results`              - Check the fixer results
 `AssertFixerNotExecuted`           - Check that fixers will not be executed.
 
-
 ===============================================================================
 4.3 Running Tests in a Windows VM               *ale-development-windows-tests*
 
@@ -463,4 +462,75 @@ Unless configuring GitHub to expose contact details, commits will be rewritten
 to appear by `USERNAME <RANDOM_NUMBER+USERNAME@users.noreply.github.com>` .
 
 ===============================================================================
+5.1 Preparing a Release                               *ale-development-release*
+
+ALE offers release packages through GitHub, for two reasons:
+
+1. Some users like to target specific release versions rather than simply
+   installing the plugin from `master`. This includes users who create Linux
+   distribution specific packages from GitHub releases.
+2. The releases provide a nice way to get an overview of what has changed in
+   ALE over time.
+
+ALE has no fixed release schedule. Release versions are created whenever the
+ALE developers feel the need to create one. ALE release versions follow the
+typical Semantic Versioning scheme. See: https://semver.org/
+
+Minor version releases for ALE should be the most common, followed by patch
+releases. Every minor version release should be followed by a `vA.B.x` branch
+such as `v2.0.x` for version `2.0.0` and every following patch version before
+`2.1.0`. The `git` branch strategy for patches is to first merge a bug fix to
+`master`, and then `git cherry-pick` a patch to a branch for a specific
+version. ALE developers do not generally support anything but `master` or the
+last minor version.
+
+Generally ALE releases hit a major version only when there are breaking
+changes to a public ALE setting or function. A "public" setting or function is
+defined as any setting or function documented in the `:help` |ale| text file.
+Major ALE versions ought to be so rare that they only come once a year at
+most. ALE should not typically introduce any breaking changes.
+
+If there are ever to be any breaking changes made for ALE, there should first
+come a minor version release for ALE documenting all of the coming breaking
+changes to ALE. It should be described how users can prepare for a breaking
+change that is coming before it is done.
+
+To create a release for ALE, you will need sufficient permissions in GitHub.
+Once you do, follow these steps.
+
+1. Create a new release draft, or edit an existing one. It helps to craft
+   drafts ahead of time and write the last commit ID checked for release notes
+   on the last update to a draft.
+   See the releases page: https://github.com/dense-analysis/ale/releases
+2. Examine `git log` and read changes made between the last ID checked, or the
+   git tag of the previous release, and the current commit in `master`.
+3. Write updates in separate sections (except where empty) for:
+  3.a. Breaking Changes
+  3.b. Deprecated Features
+  3.c. New Features
+  3.d. New Linters
+  3.e. New Fixers
+  3.f. Linter Enhancements
+  3.g. Fixer Enhancements
+  3.h. Bugs Fixed
+4. Once you've finished writing the draft for the release, bump
+   `s:current_ale_version` in `autoload/ale.vim` to the current version, and
+   add a line to `test/test_ale_has.vader` to test for the version. See
+   |ale#Has()| documentation for more information.
+5. Commit the changes after `./run-tests --fast -q` passes.
+6. Tag the release with `git tag vA.B.C`, replacing `A`, `B`, and `C` with the
+   version numbers. See `git tag --list` for examples.
+7. Run `git push` and `git push --tags` to push the commit and the tag.
+8. Edit the release draft in GitHub, select the tag you just pushed, and
+   publish the draft.
+9. If you're creating a new major or minor version: `git checkout -b vA.B.x`,
+   replacing `A` and `B` with the major and minor versions. `git push` the new
+   branch, and the GitHub branch protection settings should automatically
+   apply to the new release branch.
+10. You have already completed the last step.
+
+Have fun creating ALE releases. Drink responsibly, or not at all, which is the
+preference of w0rp.
+
+===============================================================================
   vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl: