add versioning policyHEADmain

1 files changed, 21 insertions, 0 deletions

diff --git a/README b/README
index 90e8eca..2126d3a 100644
--- a/README
+++ b/README
@@ -11,3 +11,24 @@ metadata, set the bucket name in the `R2_BUCKET` environment variable and
 specify the release tag with `TAG`, then run the Makefile target:
 
     R2_BUCKET=<your-bucket-name> TAG=<version> make deploy
+
+
+Versioning
+----------
+
+This package follows the version format `MAJOR.MINOR.YYYYMMDD`.
+
+The patch component uses a date instead of an incrementing number to
+make the freshness of the metadata immediately visible.
+
+- **Major** version increments indicate breaking changes to the metadata
+  schema.
+- **Minor** version increments indicate backward-compatible changes to
+  the metadata schema.
+- **Patch** version represents the metadata snapshot date in `YYYYMMDD`
+  format and indicates when the metadata was generated from Alibaba
+  Cloud.
+
+Consumers should depend on `^MAJOR.MINOR`, for example:
+
+    "lizhineng/afterglow-metadata": "^1.0"