From e85e888f9223f24bd74bb4c9564c99f87c99f111 Mon Sep 17 00:00:00 2001
From: Daniel Chao <dan.chao@apple.com>
Date: Wed, 5 Feb 2025 11:24:41 -0800
Subject: [PATCH] [docs] Add documetation about release/evolution/roadmap
 (#937)

---
 .../ROOT/pages/evolution-and-roadmap.adoc     | 20 +++++++++++++++++++
 docs/modules/release-notes/pages/index.adoc   |  2 ++
 docs/nav.adoc                                 |  2 ++
 3 files changed, 24 insertions(+)
 create mode 100644 docs/modules/ROOT/pages/evolution-and-roadmap.adoc

diff --git a/docs/modules/ROOT/pages/evolution-and-roadmap.adoc b/docs/modules/ROOT/pages/evolution-and-roadmap.adoc
new file mode 100644
index 00000000..c70122f3
--- /dev/null
+++ b/docs/modules/ROOT/pages/evolution-and-roadmap.adoc
@@ -0,0 +1,20 @@
+= Evolution and Roadmap
+
+:uri-pkl-roadmap: https://github.com/orgs/apple/projects/12/views/1
+:uri-pkl-evolution: https://github.com/apple/pkl-evolution
+
+== Evolution
+
+Sometimes, a change to Pkl is large enough that it makes sense to create a proposal for the change so that it can be discussed in detail and vetted.
+
+Pkl has a process for managing such designs in a repository called {uri-pkl-evolution}[Pkl Evolutiuon].
+
+== Roadmap
+
+To discover what might be coming in future versions, reference the {uri-pkl-roadmap}[Pkl Roadmap] project on GitHub.
+
+The roadmap describes estimates.
+The Pkl team aims to cut a release in February, June, and October of each year.
+If an item is not complete by the release cutoff date, the roadmap item may be bumped to the next release.
+
+Additionally, as priorities change, it is possible that items can be moved around, or backlogged.
diff --git a/docs/modules/release-notes/pages/index.adoc b/docs/modules/release-notes/pages/index.adoc
index 147e71c4..f178ab2f 100644
--- a/docs/modules/release-notes/pages/index.adoc
+++ b/docs/modules/release-notes/pages/index.adoc
@@ -1,5 +1,7 @@
 = Release Notes
 
+The Pkl team aims to release a new version of Pkl in February, June, and October of each year.
+
 * xref:0.28.adoc[0.28 Release Notes]
 * xref:0.27.adoc[0.27 Release Notes]
 * xref:0.26.adoc[0.26 Release Notes]
diff --git a/docs/nav.adoc b/docs/nav.adoc
index e35274ec..622beaae 100644
--- a/docs/nav.adoc
+++ b/docs/nav.adoc
@@ -38,6 +38,8 @@
 
 * xref:ROOT:examples.adoc[Examples]
 
+* xref:ROOT:evolution-and-roadmap.adoc[Evolution and Roadmap]
+
 * xref:release-notes:index.adoc[Release Notes]
 ** xref:release-notes:0.28.adoc[0.28 Release Notes]
 ** xref:release-notes:0.27.adoc[0.27 Release Notes]