releasing docs #674
releasing docs #674
Conversation
Kelerchian
force-pushed
the
ada/release-docs
branch
from
cac1e96
to
783d08e
Compare
Kelerchian
force-pushed
the
ada/release-docs
branch
from
783d08e
to
ab86199
Compare
There was a problem hiding this comment.
Thanks for starting this. I think the structure is good (apart from the placement of the glossary), and it will grow a few more (sub)sections as noted.
The graph still depicts the old release flow and needs to be updated. Here, all actions are triggered by pushes to some branch, right? I’d phrase it as such, the wording “merge to” is less clear.
| @@ -0,0 +1,36 @@ | |||
| # Releasing Guide | |||
|
|
|||
| AX releasing workflow is semi-guided by the CI logic comprised of [GitHub actions scripts](.github/workflows/), [makefile](./Makefile), and [cosmos-release tool](./rust/release/). | |||
There was a problem hiding this comment.
“comprised of” is almost always incorrect: to comprise means to “take together”, i.e. to gather, so “comprised of” would mean “gathered by”.
| AX releasing workflow is semi-guided by the CI logic comprised of [GitHub actions scripts](.github/workflows/), [makefile](./Makefile), and [cosmos-release tool](./rust/release/). | |
| The AX releasing workflow is semi-guided by the CI logic comprising [GitHub actions scripts](.github/workflows/), [makefile](./Makefile), and [cosmos-release tool](./rust/release/). |
| 1. After **Release PR** is merged to the `master` branch, a publication process will run; it publishes all **products** listed on the previously merged release. | ||
| 1. _[Manually]_ A developer publishes `rust` crates that have been changed. | ||
|
|
||
| ## Glossary: |
|
|
||
| > - Note: Explanations for the text in bold can be found in the [glossary section](#glossary). | ||
|
|
||
| 1. A release starts when a **changelog commit** is created. |
There was a problem hiding this comment.
“Created” would probably be understood widely, including when I create the commit on my laptop — but that doesn’t start the release. I’d say it starts when a changelog is pushed to master (which regularly occurs via a PR).
| 1. _[Manually]_ With a developer's assistance, each impacted **product's** version is bumped correctly. These product's version can be found in each of the corresponding cargo.toml or package.json file. | ||
| 1. _[Manually]_ the **Release PR** is merged when its build and validation chain is successful. | ||
| 1. After **Release PR** is merged to the `master` branch, a publication process will run; it publishes all **products** listed on the previously merged release. | ||
| 1. _[Manually]_ A developer publishes `rust` crates that have been changed. |
There was a problem hiding this comment.
The process you describe is the old one, you guys changed all this on Monday, right?
| ## Glossary: | ||
|
|
||
| - **`Actyx` Product**: or simply product, refers to publishable artifacts from this repository (`ax`, `ax-core`, `node-manager`, etc). | ||
| - **changelog commit**: a conventional commit with a valid product designation that will trigger a release process and will be included in the release changelog. |
There was a problem hiding this comment.
This line should describe exactly how a changelog is attached to a commit instead of the consequences this will have down the line. It should probably point to a section below detailing the changelog entry syntax.
|
|
||
| - **`Actyx` Product**: or simply product, refers to publishable artifacts from this repository (`ax`, `ax-core`, `node-manager`, etc). | ||
| - **changelog commit**: a conventional commit with a valid product designation that will trigger a release process and will be included in the release changelog. | ||
| - **versions file**: is a special file that lists supposedly released versions of **`Actyx` products**. This file is located [here](./versions). |
There was a problem hiding this comment.
The “supposedly” will be confusing to the reader. Perhaps better remove it and add a remark that released is not the same as published, pointing to the description of the publishing mechanism.
| - **changelog commit**: a conventional commit with a valid product designation that will trigger a release process and will be included in the release changelog. | ||
| - **versions file**: is a special file that lists supposedly released versions of **`Actyx` products**. This file is located [here](./versions). | ||
| - **Release PR**: An automatically generated Pull Request for release purposes. It contains a changelog and the appending of the **version file**. | ||
| - **Databank**: refers to the set of storage rules and the communication protocol inside `ax-core`. Previously this was a standalone binary simply called `Actyx`. A **Databank** has a version number to co-identify whether it has a compatible communication protocol with a peer **Databank**. |
There was a problem hiding this comment.
| - **Databank**: refers to the set of storage rules and the communication protocol inside `ax-core`. Previously this was a standalone binary simply called `Actyx`. A **Databank** has a version number to co-identify whether it has a compatible communication protocol with a peer **Databank**. | |
| - **databank version**: refers to the set of storage rules, communication protocols, and other behaviours inside `ax-core`. | |
| This is necessary because the Rust crate version of `ax-core` is dictated by semantic versioning, which regards only the exposed data types and function signatures, i.e. an orthogonal set of concerns. | |
| The databank version continues to denote what was previously the version of the `Actyx` binary (when `ax` was only its remote management CLI). |
|
|
||
| ## Versioning and Development Policy Regarding Version Interdependency | ||
|
|
||
| `ax`, `ax-core`, and **Databank** have version interdependency, namely, a major and minor bump in `ax` results in the **Databank** version bump. Because of this, some rules are needed. |
There was a problem hiding this comment.
| `ax`, `ax-core`, and **Databank** have version interdependency, namely, a major and minor bump in `ax` results in the **Databank** version bump. Because of this, some rules are needed. | |
| `ax`, `ax-core`, and **databank** have version interdependencies, because of the policy decision that the `ax` version shall match the databank version, where the former has a patch component and the latter has not. | |
| This inspires the following rules: |
|
|
||
| `ax`, `ax-core`, and **Databank** have version interdependency, namely, a major and minor bump in `ax` results in the **Databank** version bump. Because of this, some rules are needed. | ||
|
|
||
| - **Databank** version reflects the protocol inside while `ax-core` version reflects its API. |
There was a problem hiding this comment.
| - **Databank** version reflects the protocol inside while `ax-core` version reflects its API. | |
| - **databank** version reflects the protocol inside while `ax-core` version reflects its Rust API. |
| `ax`, `ax-core`, and **Databank** have version interdependency, namely, a major and minor bump in `ax` results in the **Databank** version bump. Because of this, some rules are needed. | ||
|
|
||
| - **Databank** version reflects the protocol inside while `ax-core` version reflects its API. | ||
| - **Databank** version inside `ax-core` that is being included in `ax` must be the `ax`'s `major.minor` version format. |
There was a problem hiding this comment.
| - **Databank** version inside `ax-core` that is being included in `ax` must be the `ax`'s `major.minor` version format. | |
| - **databank** version inside `ax-core` that is being included in `ax` must be `ax`'s `major.minor` version part. |
Not all actions, but the version check happens inside "validate" fires on all updates on PRs (which, when the merging rule is set as it is right now, is an indicator of an upcoming merge). Although, one thing I think is still missing is the complete protection from:
|
|
Let’s try to complete this soon — we need to get back to releasing. @jmg-duarte could you also review regarding the current state of affairs? |
No description provided.