From 041fd3778e779f1d2301e10a5a3dbdfc84f76874 Mon Sep 17 00:00:00 2001
From: Jim Lawson
Date: Tue, 12 Nov 2019 11:22:47 -0800
Subject: Add brief description of (current) chisel versioning and version
 recommendations. (#1180)

* Add brief description of (current) chisel versioning and version recommendations.

* Respond to comments.
Replace "semantic versioning" with "a form of semantic versioning".

* Respond to comments - replace mmddyy with yyyymmdd.

* Mention change in SNAPSHOT naming.
---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 00fd3822..82a2cab8 100644
--- a/README.md
+++ b/README.md
@@ -179,3 +179,27 @@ Also included is:
 - **Driver utilities**, `chisel3.Driver`, which contains compilation and test
   functions that are invoked in the standard Verilog generation and simulation
   testing infrastructure. These can also be used as part of custom flows.
+
+### Which version should I use?
+
+The chisel eco-system (`chisel3`, `firttl`, `dsptools`, `firrtl-interpreter`, `treadle`, `diagrammer`) use a form of semantic versioning:
+ major versions are identified by two leading numbers, separated by a dot (i.e., `3.2`), minor versions by a single number following the major version, separated by a dot.
+ We maintain API compatibility within a major version (i.e., `3.2.12` should be API-compatible with `3.2.0`), but do not guarantee API compatibility between major versions
+ (i.e., APIs may change between `3.1.8` and `3.2.0`).
+ We may introduce new definitions or add additional parameters to existing definitions in a minor release, but we do our best to maintain compatibility with previous minor releases of a major release - code that worked in `3.2.0` should continue to work un-modified in `3.2.10`.
+
+We encourage chisel users (rather than chisel developers), to use release versions of chisel.
+ The chisel web site (and GitHub repository) should indicate the current release version.
+ If you encounter an issue with a released version of chisel, please file an issue on GitHub mentioning the chisel version and provide a simple test case (if possible).
+ Try to reproduce the issue with the associated latest minor release (to verify that the issue hasn't been addressed).
+
+If you're developing a chisel library (or `chisel` itself), you'll probably want to work closer to the tip of the development trunk.
+ By default, the master branches of the chisel repositories are configured to build and publish their version of the code as `Z.Y-SNAPSHOT`.
+ We try to publish an updated SNAPSHOT every two weeks.
+ There is no guarantee of API compatibility between SNAPSHOT versions, but we publish date-stamped `Z.Y-yyyymmdd-SNAPSHOT` versions which will not change.
+ The code in `Z.Y-SNAPSHOT` should match the code in the most recent `Z.Y-yyyymmdd-SNAPSHOT` version, the differences being the chisel library dependencies:
+ `Z.Y-SNAPSHOT`s depend on `V.U-SNAPSHOT`s and `Z.Y-yyyymmdd-SNAPSHOT`s will depend on `V.U-yyyymmdd-SNAPSHOT`s.
+ **NOTE**: Prior to the `v3.2-20191030-SNAPSHOT` version, we used `Z.Y-mmddyy-SNAPSHOT` to tag and name published SNAPSHOTs.
+
+If you're developing a library (or another chisel tool), you should probably work with date-stamped SNAPSHOTs until your library or tool is ready to be published (to ensure a consistent API).
+ Prior to publishing, you should verify your code against generic (no date-stamp) SNAPSHOTs, or locally published clones of the current master branches of chisel dependencies.
-- 
cgit v1.2.3