From 34089e302c8415a34f69a200f4aee689fd97a0c8 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Fri, 6 Jul 2018 17:06:08 -0600
Subject: [PATCH] Add general documentation for maintainers

---
 changelogs/README.md                    | 55 +++++++++++++++++++++++++
 changelogs/client_server/pyproject.toml |  2 +-
 2 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/README.md

diff --git a/changelogs/README.md b/changelogs/README.md
new file mode 100644
index 00000000..10d69cb6
--- /dev/null
+++ b/changelogs/README.md
@@ -0,0 +1,55 @@
+<!-- Note: This is a markdown file so the build script's RST processing doesn't grab it -->
+
+# Changelogs
+
+[Towncrier](https://github.com/hawkowl/towncrier) is used to manage the changelog and 
+keep it up to date. Because of this, updating a changelog is really easy.
+
+## How to update a changelog when releasing an API
+
+1. Ensure you're in your Python 3 virtual environment
+2. `cd` your way to the API you're releasing (eg: `cd changelogs/client_server`)
+3. Run `towncrier --version "r0.4.0" --name "client-server" --yes` substituting the 
+   variables as approprite. Note that `--name` is required although the value is ignored.
+4. Commit the changes and finish the release process.
+
+## How to prepare a changelog for a new API
+
+For this example, we're going to pretend that the `server_server` API doesn't exist.
+
+1. Create the file `changelogs/server_server.rst`
+2. Create the folder `changelogs/server_server`
+3. In the new folder, create a `pyproject.toml` file with these contents:
+   ```toml
+   [tool.towncrier]
+    filename = "../server_server.rst"
+    directory = "newsfragments"
+    issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
+    title_format = "{version}"
+    
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "new"
+        name = "New Endpoints"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "Backwards Compatible Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "clarification"
+        name = "Spec Clarifications"
+        showcontent = true
+   ```
+4. Use the changelog in whatever RST documents you need
diff --git a/changelogs/client_server/pyproject.toml b/changelogs/client_server/pyproject.toml
index d5daface..8fa3f6b5 100644
--- a/changelogs/client_server/pyproject.toml
+++ b/changelogs/client_server/pyproject.toml
@@ -1,5 +1,5 @@
 [tool.towncrier]
-    filename = "_rendered.rst"
+    filename = "../client_server.rst"
     directory = "newsfragments"
     issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
     title_format = "{version}"