Skip to content

Commit 3f3f875

Browse files
authored
Add documentation about releases and versioning (#4469)
1 parent 0ed5700 commit 3f3f875

File tree

1 file changed

+38
-0
lines changed

1 file changed

+38
-0
lines changed

README.adoc

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,44 @@ The main documentation is located https://plutus.readthedocs.io/en/latest/[here]
6464
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.papers.utxoma/latest/download-by-type/doc-pdf/utxoma[UTXOma: UTXO with Multi-Asset Support]: a full presentation of the multi-asset ledger extension (https://doi.org/10.1007/978-3-030-61467-6_8[published version]).
6565
- https://hydra.iohk.io/job/Cardano/plutus/linux.docs.papers.eutxoma/latest/download-by-type/doc-pdf/eutxoma[Native Custom Tokens in the Extended UTXO Model]: a discussion of the interaction of the multi-asset support with EUTXO (https://doi.org/10.1007/978-3-030-61467-6_7[published version]).
6666

67+
== Versioning and releases
68+
69+
=== Versioning
70+
71+
The core `plutus` packages are versioned as follows:
72+
73+
* Package versioning follows the https://pvp.haskell.org/[PVP] on a best-effort basis (i.e. we will generally try to but we won't guarantee it).
74+
** The first-major-version component indicates the "era" which for our purposes means which major version of the *Cardano node* is being targeted.
75+
** The second-major-version component is used for releases which are major versions according to the PVP, but which are still compatible with the current "era".
76+
** The minor-version and below are used as normal.
77+
* Packages which are used downstream should all have the same version.
78+
* Other packages which are not used downstream (e.g. `plutus-benchmark`) can remain unversioned.
79+
80+
In principle we could just have a single major version, but using two makes it easier to avoid mistakes.
81+
82+
=== Branching and tagging
83+
84+
The following branching and tagging rules are followed:
85+
86+
* Version `X` is tagged as `vX`.
87+
* `master` is always targeting the next first-major-version.
88+
* First-major-version releases also have a release branch, `release/X`.
89+
** Changes will be backported from master to the release branch
90+
** Subsequent lesser releases will be made from that branch but do not create new branches.
91+
92+
=== Version ranges
93+
94+
Packages which depend on `plutus` packages should use version ranges to control which version of those packages they build against.
95+
96+
* Packages in `plutus` which are used downstream should pin the major-version of each other (e.g. `plutus-tx-1.0.1` should depend on `plutus-core ^>= 1.0`).
97+
* Downstream packages should pin at least the first-major-version of `plutus` packages.
98+
** Upgrading to a new second-major-version should always be safe, with at most code breakage (following the PVP). Users may of course want to pin this version as well to avoid such breakage.
99+
* Downstream packages pulling in `plutus` packages via `source-repository-package` stanzas should always take tagged commits, or potentially commits from a release branch.
100+
101+
=== Releases
102+
103+
Currently there is no release process beyond bumping the package versions and making a tag/branch as appropriate.
104+
67105
== Working with the project
68106

69107
=== How to submit an issue

0 commit comments

Comments
 (0)