Add documentation for version numbering and releases (#809)

* Add documentation for version numbering and releases

* Incorporate review feedback

* Update developer documentation

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
+
+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.
+- 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. These are announced in the release notes.
 
 ## Alternatives
 

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.