added section on semantic versioning

and added more info on how to generate
the repo for new versions of Unicode and CLDR.

Change-Id: I16c0cf2ed546e57da0490454cfeb8df95289c2e1
Run-TryBot: Marcel van Lohuizen <>
TryBot-Result: Gobot Gobot <>
Reviewed-by: Nigel Tao <>
diff --git a/ b/
index 4826fe8..26590f1 100644
--- a/
+++ b/
@@ -1,5 +1,23 @@
 This repository holds supplementary Go libraries for text processing, many involving Unicode.
+# Semantic Versioning
+This repo uses Semantic versioning (, so
+1. MAJOR version when you make incompatible API changes,
+1. MINOR version when you add functionality in a backwards-compatible manner, and
+1. PATCH version when you make backwards-compatible bug fixes.
+A Unicode major and minor version bump is mapped to a major version bump in
+A path version bump in Unicode is mapped to a minor version bump in x/text.
+Note that, consistent with the definitions in semver, until version 1.0.0 of
+x/text is reached, the minor version is considered a major version.
+So going from 0.1.0 to 0.2.0 is considered to be a major version bump.
+A major new CLDR version is mapped to a minor version increase in x/text.
+Any other new CLDR version is mapped to a patch version increase in x/text.
+# Contribute
 To submit changes to this repository, see
 To generate the tables in this repository (except for the encoding tables),
@@ -8,16 +26,38 @@
 Running go generate will as a side effect create a DATA subdirectory in this
-directory which holds all files that are used as a source for generating the
+directory, which holds all files that are used as a source for generating the
 tables. This directory will also serve as a cache.
+## Testing
-	go test ./...
+    go test ./...
 from this directory to run all tests. Add the "-tags icu" flag to also run
 ICU conformance tests (if available). This requires that you have the correct
 ICU version installed on your system.
-- updating unversioned source files.
\ No newline at end of file
+## Versions
+To update a Unicode version run
+    UNICODE_VERSION=x.x.x go generate
+where `x.x.x` must correspond to a directory in
+If this version is newer than the version in core it will also update the
+relevant packages there. The idna package in x/net will always be updated.
+To update a CLDR version run
+    CLDR_VERSION=version go generate
+where `version` must correspond to a directory in
+Note that the code gets adapted over time to changes in the data and that
+backwards compatibility is not maintained.
+So updating to a different version may not work.
+The files in DATA/{iana|icu|w3|whatwg} are currently not versioned.