From a8c1a4f8715f40e71d82132c3eedd5d8be44b7b9 Mon Sep 17 00:00:00 2001
From: Sebastian Wilzbach <seb@wilzba.ch>
Date: Fri, 16 Dec 2016 03:06:03 +0100
Subject: [PATCH] Move changelog to a folder and use single file entries

---
 changelog.dd        | 33 ---------------------------------
 changelog/README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 33 deletions(-)
 delete mode 100644 changelog.dd
 create mode 100644 changelog/README.md

diff --git a/changelog.dd b/changelog.dd
deleted file mode 100644
index a6d96fe1fa65..000000000000
--- a/changelog.dd
+++ /dev/null
@@ -1,33 +0,0 @@
-Ddoc
-
-$(COMMENT Pending changelog for 2.073. This will get copied to dlang.org and
-    cleared when master gets merged into stable.
-)
-
-$(BUGSTITLE Language Changes,
-    $(LI Add `D_AVX` predefined version when $(TT -mcpu=avx) is used.)
-)
-
-$(BUGSTITLE Compiler Changes,
-)
-
-$(BUGSTITLE Language Changes,
-)
-
-$(BUGSTITLE Compiler Changes,
-)
-
-Macros:
-    TITLE=Change Log
-
-    H4 = <h4>$0</h4>
-    BUGSTITLE = <div class="bugsfixed">$(H4 $1) $(OL $2 )</div>
-
-    RELATIVE_LINK2=<a href="#$1">$+</a>
-    LNAME2=<a class="anchor" title="Permalink to this section" id="$1" href="#$1">$+</a>
-
-    BUGZILLA = <a href="https://issues.dlang.org/show_bug.cgi?id=$0">Bugzilla $0</a>
-    PULL_REQUEST = $(LINK2 https://github.com/dlang/$1/pull/$2, $1#$2)
-    DMDPR = $(PULL_REQUEST dmd,$1)
-
-    BOOKTABLE = <table><caption>$1</caption>$+</table>
diff --git a/changelog/README.md b/changelog/README.md
new file mode 100644
index 000000000000..b79acf7e7251
--- /dev/null
+++ b/changelog/README.md
@@ -0,0 +1,42 @@
+This directory will get copied to dlang.org and cleared when master gets
+merged into stable prior to a new release.
+
+How to add a new changelog entry to the pending changelog?
+==========================================================
+
+Create a new file in the `changelog` folder. It should end with `.dd` and look
+similar to a git commit message. The first line represents the title of the change.
+After an empty line follows the long description:
+
+```
+My fancy title of the new feature
+
+A long description of the new feature in `std.range`.
+It can be followed by an example:
+-------
+import std.range : padLeft, padRight;
+import std.algorithm.comparison : equal;
+
+assert([1, 2, 3, 4, 5].padLeft(0, 7).equal([0, 0, 1, 2, 3, 4, 5]));
+
+assert("Hello World!".padRight('!', 15).equal("Hello World!!!!"));
+-------
+and links to the documentation, e.g. $(REF drop, std, range) or
+$(REF_ALTTEXT a custom name for the function, drop, std, range).
+
+Links to the spec can look like this $(LINK2 $(ROOT_DIR)spec/module.html, this)
+and of course you can link to other $(LINK2 https://forum.dlang.org/, external resources).
+```
+
+The title can't contain links (it's already one).
+For more infos, see the [Ddoc spec](https://dlang.org/spec/ddoc.html).
+
+Preview changes
+---------------
+
+If you have cloned the [tools](https://github.com/dlang/tools) and [dlang.org](https://github.com/dlang/dlang.org) repo),
+you can preview the changelog with:
+
+```
+make -C ../dlang.org -f posix.mak pending_changelog
+```