diff options
| -rw-r--r-- | doc/ale-development.txt | 74 |
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: |