Add documentationfor news management tool

pyproject.toml

@@ -93,3 +93,4 @@ lint = { cmd = "pre-commit run --all-files", help = "Checks all files for CI err
 precommit = { cmd = "pre-commit install --install-hooks", help = "Installs the precommit hook" }
 report = { cmd = "coverage report", help = "Show coverage report from previously run tests." }
 test = { cmd = "pytest -n auto --dist loadfile", help = "Runs tests and save results to a coverage report" }
+news-create = { cmd = "python -m scripts.news add", help = "Create a new news fragment for your PR to discord-modmail!"}

scripts/news/README.md

@@ -0,0 +1,25 @@
+# News Management Tool
+
+This writes a news fragment into a directory called `news/next`, here `next` corresponds to the next version
+of `discord-modmail`. If the directory doesn't exist, it means you are in the wrong CWD (current working directory)
+or you are running the command for the first time, in which case you need to manually create the folder.
+
+To make a new news fragment, you can run `python -m scripts.news add` or use the poetry task `news-create`. It
+will make a new file with a filename using the current date and time, GitHub pull request number and a *hopefully
+unique* 6-letter word generated by encoding the news entry text.
+
+When it is time to release `discord-modmail` 🎉, the `build` command would aggregate all the fragments present
+in `news/next` directory into a single news file for that version.
+
+
+## Concepts
+
+### Fragments
+
+Fragments are files describing your latest work, created by the `python -m scripts.news add` command. The files
+are created in the `news/next` directory.
+
+### Categories / Types
+News entries can be categorized, for example as additions, fixes, removals, and breaking changes. The list
+of categories is settable with the types setting in [config.toml](./config.toml). While making a news fragment
+entry using the `add` command, you would be asked to specify the `type`.

scripts/news/__main__.py

@@ -201,7 +201,7 @@ def cli_build_news(ctx: click.Context) -> None:
 
     template = CONFIG["core"].get("template")
     if not template:
-        template = Path(Path.cwd(), "scripts/news/default_template.md.jinja")
+        template = Path(Path.cwd(), "scripts/news/template.md.jinja")
     else:
         template = Path(Path.cwd(), f"scripts/news/{template}")
 

scripts/news/config.toml

@@ -1,6 +1,3 @@
-[core]
-template = "default_template.rst"
-
 [types]
 feature = { name = "Features" }
 trivial = { name = "Trivial/Internal Changes" }