;doc: RELEASING: glossary/process updates
This commit is contained in:
Simon Michael
parent
5a20913819
commit
cb091b26ca
66
RELEASING.md
66
RELEASING.md
@ -8,32 +8,50 @@ Tips for hledger release managers and maintainers.
|
|||||||
|
|
||||||
## Glossary
|
## Glossary
|
||||||
|
|
||||||
|
Here are terms and concepts related to the hledger release process as of 2022,
|
||||||
|
in sufficient detail to guide release management and release automation.
|
||||||
|
|
||||||
|
| | |
|
||||||
|
|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| | **General concepts** |
|
||||||
|
| *Release* | A snapshot of the software and related artifacts like executable binaries, which is named, tagged, documented, announced, and usually picked up by packaging systems on various platforms. |
|
||||||
|
| *version control system, VCS* | A tool used for storing and sharing and viewing the history and different lines of development of a software project, or other set of files. hledger uses Git. |
|
||||||
|
| *repository, repo* | A set of files being stored and managed by a VCS. Often published on a *repository hosting service*, such as Github. |
|
||||||
|
| *working copy, clone* | A local copy of a repository's files. Typically each developer has one or more of these, and can share changes easily with the official public repository. |
|
||||||
|
| *branch* | Some VCS's, including Git, can store multiple branching lines of development within one repository. A working copy can be quickly switched to a different branch to show its content. |
|
||||||
|
| *master, main* | The main branch in a repo, usually named `master` or `main`. Pull requests are usually relative to this. |
|
||||||
|
| *pull request, PR* | A request to merge a development branch with master, and any related discussion. On Github, these are kept alongside issues in the issue tracker. |
|
||||||
|
| *continuous integration, CI* | Automated actions that run when new code is pushed to a shared repo, such as running tests or producing binaries. On Github this is called Github Actions and action scripts are called *workflows*. |
|
||||||
|
| | **hledger concepts** |
|
||||||
|
| *hledger version number* | A 2-4 part dotted number naming a hledger release: `MA.JOR[.MINOR[.FIXUP]]` or <br>`MA.JOR.99[.PREVIEW]` where 99 means "unreleased (MAJOR+1)". <br>See examples below. |
|
||||||
|
| *hledger version string* | A line of text describing a hledger binary, shown by `--version`. It contains program name, version number, commit hash and date, machine architecture etc. Eg: <br>`hledger 1.24.1-g7799d526b-20211210, mac-x86_64` |
|
||||||
|
| *Full, partial, mixed releases* | A release of all the core hledger packages (hledger-lib, hledger, hledger-ui, hledger-web) is called *full*. A release of only some of the core packages is called *partial*. A release where some packages have different versions (because of a previous partial release) is called *mixed*. Major releases are always full, minor releases can be partial and/or mixed. |
|
||||||
|
| | **hledger release/build types** |
|
||||||
|
| *Major release* | hledger major releases include new features and incompatible API changes, and normally happen at the start of each quarter's third month (3/1, 6/1, 9/1, 12/1). Example version number: `1.25` |
|
||||||
|
| *Minor release* | Minor releases include only bug fixes, without API changes. These happen when needed, to fix significant bugs in the previous major release. Example version number: `1.25.2` (*"second bugfix release for 1.25"*) |
|
||||||
|
| *Fixup release* | Fixup releases fix packaging errors, with no changes to the hledger software. These should be rare. Example version number: `1.25.0.1` or `1.25.2.1` (*"first fixup release for 1.25 / 1.25.2"*) |
|
||||||
|
| *Release preview* | A preview of the upcoming major release for testers/early adopters, and a test of the release process, published as a Github release. These are not published on Hackage and should probably not be packaged. They will typically appear in the quarter's first and second month if needed. Example version number: `1.25.99.1` (*"preview 1 of 1.26"*) |
|
||||||
|
| *CI binaries* | Downloadable binaries produced by a run of the `linux`/`mac`/`windows` workflows in the hledger repo. This may happen periodically, eg weekly. A Github login is required to access these, and they disappear after a while. |
|
||||||
|
| *Dev build* | A local developer build of unreleased code. This is typically in `master` or a development/PR branch. Example version number: `1.25.99` (*"unreleased 1.26-dev"*) |
|
||||||
|
| | **hledger repos and branches** |
|
||||||
|
| *hledger repo* | The `hledger` git repository, containing the hledger software, reference manuals, and developer docs. <https://github.com/simonmichael/hledger> |
|
||||||
|
| *site repo* | The `hledger_website` git repository, containing most of the hledger website which appears at <https://hledger.org>. Usually checked out under the hledger repo as `site/`. <https://github.com/simonmichael/hledger_website> |
|
||||||
|
| *master* | The branch named `master` in the hledger repo; the main line of hledger development. Pull requests are usually relative to this. |
|
||||||
|
| *release branch* | Branches named `MA.JOR-branch` in the hledger repo, eg `1.25-branch`. Releases and release previews are always made from a release branch. |
|
||||||
|
|
||||||
| | |
|
## Cadence
|
||||||
|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
||||||
| | **Releases and versions** |
|
hledger major releases happen quarterly, at or near the start of the third month of each quarter.
|
||||||
| *Release* | A snapshot of the software and related artifacts like executable binaries, which is named, tagged, documented, announced, and usually picked up by packaging systems on various platforms. |
|
Here is the normal release/build schedule (as of 2022):
|
||||||
| *Version number* | A 2-4 part dotted number naming a hledger release, see examples below. For unreleased code it ends with .99, eg a post-1.25 / pre-1.26 build of master will show `1.25.99`. |
|
|
||||||
| *Version string* | A line of text describing a hledger binary, shown by `--version`, containing program name, version number, commit hash and date, machine architecture etc. Eg: `hledger 1.24.1-g7799d526b-20211210, mac-x86_64` |
|
| Time | Events |
|
||||||
| *Full, partial, mixed releases* | A release of all the core hledger packages (hledger-lib, hledger, hledger-ui, hledger-web) is called *full*. A release of only some of the core packages is called *partial*. A *mixed* release is one where, because of a previous partial release, some packages have different versions. Minor releases are sometimes partial or mixed. |
|
|-----------------------------------|------------------------------------------------------------------------------------------------------|
|
||||||
| | **hledger release types** |
|
| First month | Preview 1 ("alpha"), if needed, from release branch |
|
||||||
| *Major release* | hledger major releases include new features and incompatible API changes, and normally happen at the start of each quarter's last month (Mar 1, Jun 1, Sep 1, Dec 1). Example version number: `1.25` |
|
| Second month | Preview 2 ("beta"), if needed, from release branch |
|
||||||
| *Minor release* | Minor releases include only bug fixes, without API changes. These happen only when needed, to fix significant bugs in a major release. Example version number: `1.25.2` |
|
| Third month (3/1, 6/1, 9/1, 12/1) | Major release, from release branch; <br>Bump major version in master; <br>Create next release branch |
|
||||||
| *Fixup release* | Fixup releases include only fixes for packaging errors, and no changes to the hledger software. These should be rare. Example version number: `1.25.0.1` or `1.25.2.1` |
|
| As needed | Minor/fixup releases, from release branch |
|
||||||
| *Dev snapshot* | A tested snapshot of development code, usually from the master branch, on a certain date. These are not official hledger releases, and will not appear on Hackage, but are published as a Github release for testers/early adopters and to test the release process. They can happen at any time, eg at the start of a quarter's first or second month. Example version number: `1.25.20220102` |
|
| Weekly | CI downloadable binaries, weekly from master for mac & windows currently |
|
||||||
| *CI build* | A particular run of the linux/mac/windows Github workflows in the hledger repo, producing downloadable binaries. These may run more often than releases/snapshots, eg weekly. |
|
| On push to a PR or master | CI tests in that branch, usually not producing downloadable binaries |
|
||||||
| | **Version control** |
|
|
||||||
| *version control system, VCS* | A tool used for storing and sharing and viewing the history and different lines of development of a set of files, especially the source files of a software project. hledger uses Git. |
|
|
||||||
| *repository, repo* | A set of files being stored and managed by a VCS. Often published on a *repository hosting service*, such as Github. |
|
|
||||||
| *working copy, clone* | A local copy of a repository's files. Typically each developer has one or more of these, and can share changes easily with the official public repository. |
|
|
||||||
| *branch* | Some VCS's, including Git, can store multiple branching lines of development within one repository. A working copy can be quickly switched to a different branch to show its content. |
|
|
||||||
| | **hledger repos and branches** |
|
|
||||||
| *hledger repo* | The `hledger` git repository, containing the hledger software, reference manuals, and developer docs. <https://github.com/simonmichael/hledger> |
|
|
||||||
| *site repo* | The `hledger_website` git repository, containing most of the hledger website which appears at <https://hledger.org>. Usually checked out under the hledger repo as `site/`. <https://github.com/simonmichael/hledger_website> |
|
|
||||||
| *release branch* | Branches named `MA.JOR-branch` in the hledger repo, eg `1.24-branch`. Releases are always made from a corresponding release branch (from 2022 on). |
|
|
||||||
| *master* | The branch named `master` in the hledger repo; the main line of hledger development. Dev snapshots, and pull requests, can be made from here. |
|
|
||||||
| | |
|
|
||||||
|
|
||||||
## 2021-12 notes
|
## 2021-12 notes
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user