From aee1cb94ac8b890a36fb70c54fafef1f760334af Mon Sep 17 00:00:00 2001
From: Mathew Polzin <matt.polzin@gmail.com>
Date: Mon, 1 Jan 2024 21:08:56 -0600
Subject: [PATCH] Add a new CHANGELOG_NEXT.md file and update documentation
 around CHANGELOG entries. (#3180)

---
 .github/pull_request_template.md |  2 +-
 CHANGELOG.md                     | 28 +++-------------------------
 CHANGELOG_NEXT.md                | 29 +++++++++++++++++++++++++++++
 CONTRIBUTING.md                  |  2 +-
 Release/CHECKLIST                |  2 +-
 5 files changed, 35 insertions(+), 28 deletions(-)
 create mode 100644 CHANGELOG_NEXT.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index df2f469b0..4b36e65b4 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -5,6 +5,6 @@
 
 <!-- Please delete this section if it doesn't apply -->
 - [ ] If this is a fix, user-facing change, a compiler change, or a new paper
-      implementation, I have updated `CHANGELOG.md` (and potentially also
+      implementation, I have updated [`CHANGELOG_NEXT.md`](https://github.com/idris-lang/Idris2/blob/main/CHANGELOG_NEXT.md) (and potentially also
       `CONTRIBUTORS.md`).
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index af5252426..5585c41c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,30 +1,8 @@
+
+This CHANGELOG describes the history of already-released versions. Please see [CHANGELOG_NEXT](./CHANGELOG_NEXT.md) for changes merged into the main branch but not yet released.
+
 # Changelog
 
-## [Next version]
-
-### Language changes
-
-### Compiler changes
-
-### Library changes
-
-#### Prelude
-
-#### Base
-
-* `Data.List.Lazy` was moved from `contrib` to `base`.
-
-* Added an `Interpolation` implementation for primitive decimal numeric types and `Nat`.
-
-* Added append `(++)` for `List` version of `All`.
-
-#### Contrib
-
-* `Data.List.Lazy` was moved from `contrib` to `base`.
-
-* Existing `System.Console.GetOpt` was extended to support errors during options
-  parsing in a backward-compatible way.
-
 ## v0.7.0
 
 ### Language changes
diff --git a/CHANGELOG_NEXT.md b/CHANGELOG_NEXT.md
new file mode 100644
index 000000000..990ebc726
--- /dev/null
+++ b/CHANGELOG_NEXT.md
@@ -0,0 +1,29 @@
+
+This CHANGELOG describes the merged but unreleased changes. Please see [CHANGELOG](./CHANGELOG.md) for changes to all previously released versions of Idris2. All new PRs should target this file (`CHANGELOG_NEXT`).
+
+# Changelog
+
+## [Next version]
+
+### Language changes
+
+### Compiler changes
+
+### Library changes
+
+#### Prelude
+
+#### Base
+
+* `Data.List.Lazy` was moved from `contrib` to `base`.
+
+* Added an `Interpolation` implementation for primitive decimal numeric types and `Nat`.
+
+* Added append `(++)` for `List` version of `All`.
+
+#### Contrib
+
+* `Data.List.Lazy` was moved from `contrib` to `base`.
+
+* Existing `System.Console.GetOpt` was extended to support errors during options
+  parsing in a backward-compatible way.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7161fbba0..d196a66dd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -53,7 +53,7 @@ we haven't been too prescriptive about this. If you're editing a source file,
 try to be consistent with the existing style choices made by previous authors.
 We may need to be more formal about this in future!
 
-Please remember to update `CHANGELOG.md`, and if it's your first contribution
+Please remember to update `CHANGELOG_NEXT.md`, and if it's your first contribution
 you can add yourself to `CONTRIBUTORS`.
 
 In all cases, a pull request must have a short description (one sentence is
diff --git a/Release/CHECKLIST b/Release/CHECKLIST
index a55f3ced4..5a0038a1c 100644
--- a/Release/CHECKLIST
+++ b/Release/CHECKLIST
@@ -10,7 +10,7 @@
 [x] Change version number in tests pkg010 and pkg017  (TODO: make this step unnecessary!)
     N.B. There are 2 instances of these: tests/idris2/ and tests/idris2/pkg/
 [x] Make sure INSTALL.md gives the correct minimum Idris version
-[x] Update CHANGELOG.md to refer to the "Next version" changes as the new
+[x] Move CHANGELOG_NEXT.md entries into CHANGELOG.md under a heading for the upcoming release version. Reset CHANGELOG_NEXT.md.
     release version, leaving the next "Next version" blank.
 [x] Update bootstrap chez and racket (built with new version)
     [x] Compile Idris2 with the appropriate CG