Skip to content

docs: Update release process #423

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zanicar merged 6 commits into from
Aug 2, 2023
Merged

docs: Update release process #423

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0e93246
docs: Update release process
zanicar Jul 25, 2023
45b077f
chore: Update changelog
zanicar Jul 26, 2023
46b1060
docs: Update release process
zanicar Jul 26, 2023
848c9db
docs: Update release process
zanicar Jul 26, 2023
f2c48ce
Update releasing-archway.md
zanicar Jul 28, 2023
b5ac384
Update releasing-archway.md
zanicar Jul 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ Contains all the PRs that improved the code without changing the behaviours.
- [#419](https://github.com/archway-network/archway/pull/419) - Run localnet via make
- [#421](https://github.com/archway-network/archway/pull/421) - Add archwayd darwin binaries
- [#422](https://github.com/archway-network/archway/pull/422) - Add fee burn feature, fees not distributed to contracts get burned
- [#423](https://github.com/archway-network/archway/pull/423) - Update release docs
- [#425](https://github.com/archway-network/archway/pull/425) - Update ADR 004 - Contract Premiums

## [v2.0.0]
Expand Down
116 changes: 38 additions & 78 deletions releasing-archway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,74 +1,41 @@
# Archway Protocol Release Versioning

This document captures the release and versioning strategy of archway protocol software.

This document DOES NOT deal with versioning or releases of Various networks using archway protocol.

This Document DOES NOT deal with API versioning or API conventions of archway protocol

Reference: [Semantic Versioning](http://semver.org)

Legend:

- **X.Y.Z** refers to the version (git tag) of Archway Protocol that is released.
- **Network Operator** refers to an entity running a node and/or a validator and/or a relayer.
- **archway-1** refers to the chain id of archway protocl main network.
- **constantine-1** refers to the chain-id of the archway protocol "staging" public test network,
with long term support, gurantee of state persistance during upgrades and reasonably mirrors mainnet.
Dapp developers may build
and test their dapps against this testnet before launching on mainnet.
- **titus-1** refers to the the chain-id of the archway protocol "development" public test network.
This network is not expected to mirror mainnet and may have experimental features. There is no guarantee of stability or state
persistance during upgrades.

Note: Please refer to https://github.com/archway-network/networks for a registry of all public networks running archway protocol
and network specific information.

## Release versioning

### Minor version scheme and timeline
- X.Y.Z-rc.W (Branch: release-X.Y)
- When main is feature-complete for X.Y, we will cut the release-X.Y
branch and cherrypick only PRs essential to X.Y.
- If we're not satisfied with X.Y.0-rc.0, we'll release other rc releases,
(X.Y.0-rc.W | W > 0) as necessary.
- X.Y.0 (Branch: release-X.Y)
- Final release, cut from the release-X.Y branch.
- X.Y.0-rc.0 will be tagged at the same commit on the same branch.
- X.Y.Z, Z > 0 (Branch: release-X.Y) ([Patch releases](#patch-releases))
- [Patch releases](#patch-releases) are released as we cherrypick commits from main into
the release-X.Y branch, as needed.
- X.Y.Z is cut straight from the release-X.Y branch, and X.Y.Z+1-beta.0 is
tagged on the followup commit.
- X.Y.Z, Z > 0 (Branch: release-X.Y.Z) (Branched [patch releases](#patch-releases) only for hotfix situations)
- These are rarely used and are special in that the X.Y.Z tag is branched to isolate
the emergency/critical fix from all other changes that have landed on the
release branch since the previous tag
- Cut release-X.Y.Z branch to hold the isolated patch release
- Tag release-X.Y.Z branch + fixes with X.Y.(Z+1)
- Branched [patch releases](#patch-releases) are rarely needed but used for
emergency/critical fixes to the latest release

### Major version timeline

There is currently no mandated timeline for major versions beyond version 1.Y.Z, Y,Z >= 0. We haven't so far applied a rigorous interpretation of semantic
versioning with respect to incompatible changes of any kind.

TODO: Major versioning criteria need to be put up for discussion once Archway protocol reaches 1.Y.Z release.

## Patch releases

Patch releases are intended for critical bug fixes to the latest minor version,
such as addressing security vulnerabilities, fixes to problems affecting a large
number of users and severe problems with no workaround.

They should not contain miscellaneous feature additions or improvements, and
especially no incompatibilities should be introduced between patch versions of
the same minor version (or even major version).

Dependencies, such as cosmos-sdk or tendermint, should also not be changed unless
absolutely necessary, and also just to fix critical bugs (so, at most patch
version changes, not new major nor minor versions).
# Archway Protocol Release Process

## Release Versioning

This document outlines the release process for Archway protocol software.

The **Archway** protocol follows a **state versioning system**, it does not utilize traditional [semantic versioning](http://semver.org); SemVer is specifically about APIs, but API breaking changes is not the only way in which libraries can "break". In deterministic systems, such as a blockchain, *state breaking changes far outweigh API breaking changes*. As such, Archway follows a State Versioning system.

Given a version number Major.Minor.Patch, increment the:

1. **Major** version when any state breaking changes are introduced;
2. **Minor** version when any Query API changes, both API-compatible or API-incompatible, are introduced;
3. **Patch** version when any state-compatible bug fixes are introduced;

Additional labels for release-candidates, pre-release versions and other build metadata are available as extensions to the Major.Minor.Patch format.

**Note:** Any dependency updates that are not state breaking, e.g. updating the Go version, fall under minor.

@spoo-bar spoo-bar Jul 28, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would prefer to have it documented how often we would Minor and Patch bump when there are no consensus breaking changes.

Eg. we do a go version update with no state break, do we immediately tag that with minor bump so any new validators and nodes can use this latest instead?

Do we make a new release every time we merge to main something which isnt meta change(e.g ci or workflow or docs)? So basically, any binary change PR to main would be accompanied with a release?

@spoo-bar spoo-bar Jul 28, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If yes, would similar logic apply for consensus breaking changes? Do we tag a major version as soon as a state breaking PR is merged? (Tangent: Would be nice to have some gh workflow which checks that when there is a major version bump, an upgrade handler for that version must exist)

If no, does that mean we should batch the non state breaking changes into single release? What would be the release schedule in such case?

@zanicar zanicar Jul 28, 2023

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are great questions! It would largely depend on the perceived impact of the update across the ecosystem.

Consider for example if we do a non-state breaking, but API breaking change; We probably don't want to immediately tag and release this to provide developers time to integrate and test. Thus, we might prefer to do such a release more akin to a major update with some formal coordination;

Conversely, if we update the Go version, which would result in a minor version bump, we could immediately tag such a release as its impact would be mostly superficial;

I do like the idea of having a workflow to check for an upgrade handler for that version 👍🏻

In general, I believe we should be more selective with major version releases and handle them on a case by case basis. IMHO blockchain release is more akin to traditional software pre-Internet era, as patches and fixes could not easily be rolled out. Thus greater care needs to be taken with each major release as the "move fast and break things" approach is disconcerting in an immutable state (blockchain) environment.

@zanicar zanicar Jul 28, 2023

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding the distinction between binary updates vs non-binary updates...

We could simply add any non-binary updates, e.g. docs, workflows, etc. under unreleased version until we have an actual binary update and tag along with the updated binary release; I believe this will provide for a more consistent upgrade path where every release is associated with a binary update.


## State Compatability

**Note:** State breaking changes include changes that impact the amount of gas needed to execute a transaction as well as any changes to error handling. This is because `AppHash` and `LastResultsHash` contains:

1. Tx `GasWanted`;
2. Tx `GasUsed` - which is Merkelized, thus any logic affecting this will result in state changes;
3. Tx response `Data` - protobuf encoding changes result in state changes;

@spoo-bar spoo-bar Jul 28, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the msgs format in a transaction are also state breaking. So the Tx input as well as Tx response

4. Tx response `Code` - any changes to error handling flow, or custom error codes will result in state changes;

## Release Process

The standard release process progresses through the following steps:

1. Tag a new release once a major release, update or patch is deemed ready for deployment (release atrifacts are created via automation);
2. Deploy the new release version to Constantine (testnet);
3. Conduct final verification for the release on testnet, including verfification of upgrade handlers;
4. Repeat steps 1-3 until all verification passes, e.g. relevant tests, remediations, etc;
5. Deploy the release to mainnet via upgrade proposal;

**Note:** Steps 1-3 may include a number of iterations with various release candidates;

## Network Upgrades

Expand All @@ -85,13 +52,6 @@ version changes, not new major nor minor versions).
- titus-1 is an unstable development network, with no guarantees for stability or graceful upgrades. Network upgrades on titus-1 are
expected to reset network state and start again from block 1 at any given time.

### Open Questions in Network upgrades:

- How to build artifacts for titus-1?
- Should there be a build on each new commit on main branch?
- use X.Y.0-{alpha,beta}.W, W > 0 (Branch: master)
Alpha and beta releases are created from tags on main branch branch and should be used to run titus-1

### Important upgrade scenarios with examples

The following scenarios have hypothetical versions and do not reflect versions of actual live networks
Expand Down
⚡