From eeb1f049dd7cdef3020ad7f54b54d8eff52e5fe9 Mon Sep 17 00:00:00 2001
From: Yusuke Tsutsumi <yusuke@tsutsumi.io>
Date: Fri, 7 Apr 2023 15:49:54 -0700
Subject: [PATCH] feat(AIP-3) add versioning (#1055)

Adding an AIP to introduce versioning,
to help API authors point at older AIP guidance
as it evolves.
---
 aip/general/0003.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 aip/general/0003.md

diff --git a/aip/general/0003.md b/aip/general/0003.md
new file mode 100644
index 000000000..92a4581e7
--- /dev/null
+++ b/aip/general/0003.md
@@ -0,0 +1,45 @@
+---
+id: 3
+state: approved
+created: 2023-03-28
+placement:
+  category: meta
+  order: 30
+---
+
+# AIP Versioning
+
+This AIP defines the versioning scheme of the AIPs.
+
+## Guidance
+
+- The AIPs **must** be versioned by date, using the [ISO-8601 format of
+  `YYYY-MM-DD`](https://www.w3.org/TR/NOTE-datetime), that corresponds to the
+  date the version was added.
+- AIPs versions **must** be available as a tag on the source control system used
+  to store the AIPs, of the format `v{version}`. Example: `v2023-03-28`.
+- The AIPs **must** have a new version when there is a significant change to one
+  or more AIPs.
+- Each AIP **must** include a changelog section, with the date the change was
+  made and a short description.
+
+## Rationale
+
+Versions serve as reference points to AIPs at a specific point in time. They are
+crucial since guidance on an AIP can be reversed, or include significant changes
+such that they are no longer similar to the original design. APIs using AIPs may
+need to reference older AIP guidance to justify their design choice.
+
+### Rationale for date-based versioning
+
+With date-based versioning, a client can easily find the AIP guidance at the
+time an API was authored.
+
+### Why not individually versioned AIPs
+
+An alternative to a universal version is to have specific versions attached to
+each AIP.
+
+AIPs often cross-reference one another. If each AIP had a specific version, then
+cross-references would also have to specify specific versions of those
+referenced AIPs to provide complete guidance.
\ No newline at end of file