;doc: RELEASING: glossary updates
This commit is contained in:
Simon Michael
parent
ebf4d09537
commit
58bc3728b9
51
RELEASING.md
51
RELEASING.md
@ -8,31 +8,36 @@ Tips for hledger release managers and maintainers.
|
||||
|
||||
## Glossary
|
||||
|
||||
| | |
|
||||
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| *Release* | A named, tagged, documented, usually announced snapshot of the software plus any related artifacts like executable binaries. |
|
||||
| *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 the `--version` flag. It includes the tool name, version number, commit hash and date, machine architecture, etc. |
|
||||
| *Major release* | Major releases include significant changes like new features and incompatible API changes. hledger major releases normally happen at start of each quarter's last month (Mar 1, Jun 1, Sep 1, Dec 1). Example version number: `1.25` |
|
||||
| *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` |
|
||||
| *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` |
|
||||
| *Test release* | A snapshot of development code, published only on github, not hackage, to exercise the release process and provide fresh binaries for testers/early adopters. These can happen any time but typically at the start of a quarter's first or second month. Example version number: `1.25.20220102` |
|
||||
| *Full release* | A release of all the core hledger packages (hledger-lib, hledger, hledger-ui, hledger-web) with all of them using the same version number. Major releases are always full releases. |
|
||||
| *Partial release* | A release of only some of the core packages. Minor releases are sometimes partial. |
|
||||
| *Mixed release* | A release where some packages have different versions, because of a previous partial release. Minor releases are sometimes mixed. |
|
||||
| *hledger repo* | The `hledger` git repository, containing the core hledger tools and docs. Official public copy: github.com/simonmichael/hledger |
|
||||
| *"master"* | The `master` branch in the hledger repo; the main line of hledger development |
|
||||
| *release branch* | Branches named `MAJORVERSION-branch` in the hledger repo, eg `1.24-branch`. Releases are made from these. |
|
||||
| *site repo* | The `hledger_website` git repository, containing the hledger.org website and additional docs. Usually checked out under the hledger repo as `site/`. |
|
||||
| *"site"* | The `master` branch in the site repo, used to generate <https://hledger.org>. |
|
||||
| *MAJORVER* | Just the MA.JOR part, eg 1.24 |
|
||||
| *OLD*, *NEW* | Previous and new pending release versions. Examples: 1.24 -> 1.24.1, 1.24.1 -> 1.24.2, 1.24.2 -> 1.25. |
|
||||
|
||||
## 2021-12
|
||||
|
||||
Starting over, again:
|
||||
| | |
|
||||
|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| | **Releases and versions** |
|
||||
| *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 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: <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 *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** |
|
||||
| *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` |
|
||||
| *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` |
|
||||
| *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` |
|
||||
| *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` |
|
||||
| *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. |
|
||||
| | **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. <br><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/`. <br><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. |
|
||||
| | |
|
||||
|
||||
- All the stuff below the horizontal rule needs review and cleanup already; consider it old.
|
||||
## 2021-12 notes
|
||||
|
||||
- All the stuff below the horizontal rule has bitrotted already; consider it old and in need of review.
|
||||
- Don't try to write down, let alone automate, every step of releasing; it's too much and too unstable.
|
||||
- Practice releasing as often as possible.
|
||||
- Keep making things a little better each time through. Simpler, more reliable, easier, faster, cheaper, higher quality.
|
||||
@ -46,7 +51,7 @@ Starting over, again:
|
||||
- **Artifacts** - generating binaries, zip files, github releases etc.
|
||||
- **Publishing** - uploading, pushing, making visible, finalising
|
||||
- **Announcing** - various announcement stages and channels
|
||||
- All releases must now be made from a release branch, for uniformity and to avoid mishaps like uploading unreleased code to hackage.
|
||||
- All releases must now be made from a release branch, for uniformity and to avoid mishaps like uploading 1.24.99 dev code to hackage.
|
||||
|
||||
## Some next goals
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user