From f31389914c9138d67d5ce27a307000f4f3f867f7 Mon Sep 17 00:00:00 2001 From: Thomas Niederberger Date: Tue, 29 Oct 2024 13:11:34 +0100 Subject: [PATCH 1/3] Add documentation for version numbering and releases --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index be96c47e2..126f7797d 100644 --- a/README.md +++ b/README.md @@ -149,6 +149,21 @@ An example project on how to upgrade from older tags can be found in the Integri If you still experience issues during upgrading, do not hesitate to create an issue for support. +## Version numbers + +We use a specififc versioning schema in order to enable us to release the same version multiple times for different polkadot releases +- Major version numbers represent the version of the substrate-api-client +- Minor version numbers represent the polkadot release + - Note that this implies that there can be breaking changes in minor releases. +- Patch/bugfix number is still used for bugfixes + +## Releases and backwards compatibility + +- We usually create a release for each new polkadot release + - This release contains all the features of our current `master` branch + - We don't create releases for polkadot bugfix releases unless there are known issues +- We don't backport features and bugfixes per default. If requested we decide on a case by case basis. +- New releases can contain breaking changes. We try to track these and announce them in the release notes. ## Alternatives From e679ed3f8f32651f0c6e829767fdeab79e338ee0 Mon Sep 17 00:00:00 2001 From: Thomas Niederberger Date: Wed, 30 Oct 2024 11:05:22 +0100 Subject: [PATCH 2/3] Incorporate review feedback --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 126f7797d..b155b90ee 100644 --- a/README.md +++ b/README.md @@ -151,7 +151,7 @@ If you still experience issues during upgrading, do not hesitate to create an is ## Version numbers -We use a specififc versioning schema in order to enable us to release the same version multiple times for different polkadot releases +Starting with release 1.16.0, we use a specific versioning schema in order to enable us to release the same version multiple times for different polkadot releases - Major version numbers represent the version of the substrate-api-client - Minor version numbers represent the polkadot release - Note that this implies that there can be breaking changes in minor releases. @@ -163,7 +163,7 @@ We use a specififc versioning schema in order to enable us to release the same v - This release contains all the features of our current `master` branch - We don't create releases for polkadot bugfix releases unless there are known issues - We don't backport features and bugfixes per default. If requested we decide on a case by case basis. -- New releases can contain breaking changes. We try to track these and announce them in the release notes. +- New releases can contain breaking changes. These are announced in the release notes. ## Alternatives From 6fe674b24f2f43fd8bf51b812f8cb8da8a76482a Mon Sep 17 00:00:00 2001 From: Thomas Niederberger Date: Thu, 31 Oct 2024 10:01:45 +0100 Subject: [PATCH 3/3] Update developer documentation --- docs/README.md | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/docs/README.md b/docs/README.md index bc3b4e11c..99e830c09 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,16 +2,11 @@ ## TODO List for a new Release If a new release is released, the following tasks need to be done: -1. Update the .toml versions in accordance with the [Semantic Versioning](#semantic-versioning) section. +1. Update the .toml versions in accordance with the [Semantic Versioning](../README.md#version-numbers) section. 2. Add a new tag to the desired commit, see the [Tag generation](#tag-generation) section. 3. Update and release the new release. -4. Publish to crates.io, see https://doc.rust-lang.org/cargo/reference/publishing.html for more info. Important: Create a new branch and change all github deps to crates.io deps. See https://github.com/scs/substrate-api-client/issues/528 for an example update. - -## TODO list for a new Parity release branch -To follow a new partiy branch release, the following needs to be done: -1. Create a new branch with the same name as the parity release and update dependencies. See this [commit](https://github.com/scs/substrate-api-client/commit/a50833a922ff98ae59e2fc587e0ab5466b3acab2) for an example update. Release branches are based on a specific api-client release, not master. -2. Push the changes on the new branch and check CI result. CI will be triggered automatically if the branch follows the naming scheme of `release-polkadot-v[0-9]+.[0-9]+.[0-9]+*`. Results can be looked up [here](https://github.com/scs/substrate-api-client/actions) -3. After CI passed, update the associated release text with the new branch. See [this release](https://github.com/scs/substrate-api-client/releases/tag/v0.16.0) as an example. +4. Create a new branch and change all github deps to crates.io deps. See https://github.com/scs/substrate-api-client/issues/528 for an example update. The [psvm](https://crates.io/crates/psvm) tool can be useful for updating the polkadot dependencies. +5. Publish to crates.io, see https://doc.rust-lang.org/cargo/reference/publishing.html for more info. ## Automatic Release generation @@ -23,13 +18,6 @@ Example release: https://github.com/scs/substrate-api-client/releases/tag/v0.10. The `🎉 Featuring` section has been created manually. It should show the user directly what has been updated and what new features have been added (not only PR names) -### Semantic Versioning -This is not yet checked or automated by CI, but it may be in the future. Currently, the api-client is following the semantic versioning în pre-release as the public API may change any time. -In case a new release is triggered, the `.toml` versions of the crates, that have been updated since the last release, should be increased. -- In case of breaking API changes, the minor version should be increased (`0.9.3 -> 0.10.0`) -- In case of changes, which do not break the API, the patch version should be increased (`0.9.3 -> 0.9.4`). -The version of the main .toml should be same as the one of the release. - ### PR Labels For automatic release generation, `E` and `F` labels are used.