From 03ec2156988ddef35272365fb86415511eafb4e2 Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Thu, 18 Mar 2021 23:30:05 -0700 Subject: Update the FAQ and add doc on versioning (#1827) * Update the FAQ and add doc on versioning * Update modules.md Co-authored-by: Megan Wachs --- docs/src/appendix/appendix.md | 1 + docs/src/appendix/versioning.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 docs/src/appendix/versioning.md (limited to 'docs/src/appendix') diff --git a/docs/src/appendix/appendix.md b/docs/src/appendix/appendix.md index 48106fe4..0efedbfe 100644 --- a/docs/src/appendix/appendix.md +++ b/docs/src/appendix/appendix.md @@ -11,3 +11,4 @@ This section covers some less-common Chisel topics. * [Differences between Chisel3 and Chisel2](chisel3-vs-chisel2) * [Experimental Features](experimental-features) * [Upgrading from Scala 2.11](upgrading-from-scala-2-11) +* [Versioning](versioning) diff --git a/docs/src/appendix/versioning.md b/docs/src/appendix/versioning.md new file mode 100644 index 00000000..8c5ef91c --- /dev/null +++ b/docs/src/appendix/versioning.md @@ -0,0 +1,35 @@ +--- +layout: docs +title: "Versioning" +section: "chisel3" +--- + +# Chisel Project Versioning + +Chisel and related projects follow a versioning scheme similar to [PVP](https://pvp.haskell.org/). +Project versions are of the form `A.B.C` where `A.B` specifies the _Major_ version and `C` specifies the _Minor_ version. +Projects maintain _binary compatibility_ between minor versions of the same major version. +For example, a project compiled against Chisel3 version 3.4.0 can be used with Chisel3 version 3.4.2 or 3.4.15 without recompilation. + +# Compatible Versions + +Historically, due to a mistake in versioning with chisel-iotesters as well as some projects originating later than others, +the compatible versions of Chisel-related projects has not been obvious. +We are taking steps to improve the situation by bringing the major versions more in line (the `B` part in `A.B.C`), +but the inconsistencies remain in previously published versions. + +Please use the following table to determine which versions of the related projects are compatible. +In particular, versions of projects in this table were compiled against the version of any dependencies listed in the same row. +For example, `chisel-iotesters` version 1.4 was compiled against `chisel3` version 3.3. + +| chisel3 | chiseltest | chisel-iotesters | firrtl | treadle | diagrammer | firrtl-interpreter2 | +| ------- | ---------- | ---------------- | ------ | ------- | ---------- | ----- | +| 3.4 | 0.3 | 1.5 | 1.4 | 1.3 | 1.3 | 1.4 | +| 3.3 | 0.2 | 1.4 | 1.3 | 1.2 | 1.2 | 1.3 | +| 3.2 | 0.11 | 1.3 | 1.2 | 1.1 | 1.1 | 1.2 | +| 3.1 | - | 1.2 | 1.1 | 1.0 | 1.0 | 1.1 | +| 3.0 | - | 1.1 | 1.0 | -3 | - | 1.0 | + +1 chiseltest 0.1 was published under artifact name [chisel-testers2](https://search.maven.org/search?q=a:chisel-testers2_2.12) (0.2 was published under both artifact names) +2 Replaced by Treadle, in maintenance mode only since version 1.1 +3 Treadle was preceded by the firrtl-interpreter -- cgit v1.2.3