Add towncrier (#2873)

* Adds towncrier as our changelog system.
* Updates our contributor guidelines for this.

Resolves #2872

.github/CONTRIBUTING.md

@@ -11,8 +11,9 @@
   * [4.4 Make](#44-make)
   * [4.5 Keeping your dependencies up to date](#45-keeping-your-dependencies-up-to-date)
   * [4.6 To contribute changes](#46-to-contribute-changes)
-  * [4.7 How To Report A Bug](#47-how-to-report-a-bug)
+  * [4.7 Using towncrier](#47-using-towncrier)
-  * [4.8 How To Suggest A Feature Or Enhancement](#48-how-to-suggest-a-feature-or-enhancement)
+  * [4.8 How To Report A Bug](#48-how-to-report-a-bug)
+  * [4.9 How To Suggest A Feature Or Enhancement](#49-how-to-suggest-a-feature-or-enhancement)
 * [5. Code Review Process](#5-code-review-process)
   * [5.1 Issues](#51-issues)
   * [5.2 Pull Requests](#52-pull-requests)
@@ -98,7 +99,7 @@ Our style checker of choice, [black](https://github.com/ambv/black), actually ha
 Use the command `black --help` to see how to use this tool. The full style guide is explained in detail on [black's GitHub repository](https://github.com/ambv/black). **There is one exception to this**, however, which is that we set the line length to 99, instead of black's default 88. When using `black` on the command line, simply use it like so: `black -l 99 -N <src>`.
 
 ### 4.4 Make
-You may have noticed we have a `Makefile` and a `make.bat` in the top-level directory. For now, you can do three things with them:
+You may have noticed we have a `Makefile` and a `make.bat` in the top-level directory. For now, you can do a few things with them:
 1. `make reformat`: Reformat all python files in the project with Black
 2. `make stylecheck`: Check if any `.py` files in the project need reformatting
 3. `make newenv`: Set up a new virtual environment in the `.venv` subdirectory, and install Red and its dependencies. If one already exists, it is cleared out and replaced.
@@ -112,13 +113,37 @@ Whenever you pull from upstream (V3/develop on the main repository) and you noti
 1. Create a new branch on your fork
 2. Make the changes
 3. If you like the changes and think the main Red project could use it:
+    * Create a towncrier entry for the changes. (See next section for details)
     * Run tests with `tox` to ensure your code is up to scratch
     * Create a Pull Request on GitHub with your changes
 
-### 4.7 How To Report A Bug
+### 4.7 Using towncrier
+
+Red uses towncrier to create changelogs.
+
+To create a towncrier entry for your PR, create a file in `changelog.d` for it. If the changes are for a specific cog, place the file in the related subdirectory.
+
+The filename should be of the format `issuenumber.changetype(.count).rst`, where `(.count)` is an optional
+part of the filename should multiple entries for the same issue number and type be neccessary.
+
+Valid changetypes are:
+
+  * breaking : Breaking changes
+  * dep : Changes to dependencies
+  * enhance : Enhancements
+  * feature : New features
+  * bugfix : Bugfixes
+  * docs : documentation improvements and additions
+  * removal : removal of something
+  * misc : any changes which don't have a user facing change, and don't belong in the changelog for users
+
+The contents of the file should be a short, human readable description of the impact of the changes made,
+not the technical details of the change.
+
+### 4.8 How To Report A Bug
 Please see our **ISSUES.MD** for more information.
 
-### 4.8 How To Suggest A Feature Or Enhancement
+### 4.9 How To Suggest A Feature Or Enhancement
 The goal of Red is to be as useful to as many people as possible, this means that all features must be useful to anyone and any server that uses Red.
 
 If you find yourself wanting a feature that Red does not already have, you're probably not alone. There's bound to be a great number of users out there needing the same thing and a lot of the features that Red has today have been added because of the needs of our users. Open an issue on our issues list and describe the feature you would like to see, how you would use it, how it should work, and why it would be useful to the Red community as a whole.
@@ -137,7 +162,7 @@ Pull requests are evaluated by their quality and how effectively they solve thei
 
 1. A pull request is submitted
 2. Core team members will review and test the pull request (usually within a week)
-3. After a majority of the core team approves your pull request:
+3. After a member of the core team approves your pull request:
     * If your pull request is considered an improvement or enhancement the project owner will have 1 day to veto or approve your pull request.
     * If your pull request is considered a new feature the project owner will have 1 week to veto or approve your pull request.
 4. If any feedback is given we expect a response within 1 week or we may decide to close the PR.

Makefile

@@ -24,3 +24,8 @@ newenv:
 	$(MAKE) syncenv
 syncenv:
 	.venv/bin/pip install -Ur ./tools/dev-requirements.txt
+
+# Changelog check
+checkchangelog:
+	bash tools/check_changelog_entries.sh
+	python -m towncrier --draft

changelog.d/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/2872.feature.rst

@@ -0,0 +1 @@
+Red now uses towncrier for changelog generation

changelog.d/admin/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/alias/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/audio/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/bank/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/cleanup/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/customcom/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/downloader/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/economy/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/filter/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/general/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/image/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/mod/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/modlog/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/mutes/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/permissions/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/reports/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/streams/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/trivia/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelog.d/warnings/.gitignore

@@ -0,0 +1 @@
+!.gitignore

make.bat

@@ -30,6 +30,12 @@ goto syncenv
 .\.venv\Scripts\python -m pip install -Ur .\tools\dev-requirements.txt
 exit /B %ERRORLEVEL%
 
+:checkchangelog
+REM This should be written for windows at some point I guess.
+REM If we can swith to powershell, it can make this much easier.
+echo This doesn^'t do anything on windows ^(yet^)
+exit /b 0
+
 :help
 echo Usage:
 echo   make ^<command^>

pyproject.toml

@@ -0,0 +1,125 @@
+[tool.towncrier]
+    package = "redbot"
+    filename = "CHANGELOG.rst"
+    directory = "changelog.d"
+    issue_format = "`#{issue} <https://github.com/Cog-Creators/Red-DiscordBot/issues/{issue}>`_"
+
+    [[tool.towncrier.section]]
+        path = ""
+        name = "Core Bot Changes"
+
+    [[tool.towncrier.section]]
+        path = "admin"
+        name = "Admin"
+
+    [[tool.towncrier.section]]
+        path = "alias"
+        name = "Alias"
+    
+    [[tool.towncrier.section]]
+        path = "audio"
+        name = "Audio"
+
+    [[tool.towncrier.section]]
+        path = "bank"
+        name = "Bank"
+    
+    [[tool.towncrier.section]]
+        path = "cleanup"
+        name = "Cleanup"
+    
+    [[tool.towncrier.section]]
+        path = "customcom"
+        name = "CustomCom"
+    
+    [[tool.towncrier.section]]
+        path = "downloader"
+        name = "Downloader"
+
+    [[tool.towncrier.section]]
+        path = "economy"
+        name = "Economy"
+    
+    [[tool.towncrier.section]]
+        path = "filter"
+        name = "Filter"
+    
+    [[tool.towncrier.section]]
+        path = "general"
+        name = "General"
+    
+    [[tool.towncrier.section]]
+        path = "image"
+        name = "Image"
+    
+    [[tool.towncrier.section]]
+        path = "mod"
+        name = "Mod"
+
+    [[tool.towncrier.section]]
+        path = "modlog"
+        name = "ModLog"
+    
+    [[tool.towncrier.section]]
+        path = "mutes"
+        name = "Mutes"
+    
+    [[tool.towncrier.section]]
+        path = "permissions"
+        name = "Permissions"
+
+    [[tool.towncrier.section]]
+        path = "reports"
+        name = "Reports"
+    
+    [[tool.towncrier.section]]
+        path = "streams"
+        name = "Streams"
+    
+    [[tool.towncrier.section]]
+        path = "trivia"
+        name = "Trivia"
+    
+    [[tool.towncrier.section]]
+        path = "warnings"
+        name = "Warnings"
+
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "bugfix"
+        name = "Bug Fixes"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "enhance"
+        name = "Enhancements"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "New Feature"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "removal"
+        name = "Removals"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "misc"
+        name = "Miscellaneous changes"
+        showcontent = false
+
+    [[tool.towncrier.type]]
+        directory = "dep"
+        name = "Changes to dependencies"
+        showcontent = true
+
+    [[tool.towncrier.type]]
+        directory = "docs"
+        name = "Documentation Changes"
+        showcontent = true

setup.cfg

@@ -74,6 +74,7 @@ docs =
     sphinxcontrib-qthelp==1.0.2
     sphinxcontrib-serializinghtml==1.1.3
     sphinxcontrib-trio==1.1.0
+    towncrier==19.2.0
     urllib3==1.25.3
 mongo =
     dnspython==1.16.0

tools/check_changelog_entries.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+# This can be run for other remotes than origin with the env vat `RED_REMOTE`
+REMOTE="${RED_REMOTE:-origin}"
+
+if [[ $(git diff "$REMOTE"/V3/develop) ]]; then
+
+  if [[ $(git diff "$REMOTE"/V3/develop -- changelog.d/) ]]; then
+    echo "Found changelog fragments..."
+    exit 0
+  else
+    echo "Error: No new changelog fragments!"
+    exit 1
+  fi
+
+else
+  echo "No changes to need changelog for."
+  exit 0
+fi

tools/primary_deps.ini

@@ -30,6 +30,7 @@ docs =
     Sphinx
     sphinx_rtd_theme
     sphinxcontrib-trio
+    towncrier
 mongo =
     dnspython
     motor

tox.ini

@@ -25,12 +25,18 @@ commands =
 description = Attempt to build docs with sphinx-build
 whitelist_externals =
     sphinx-build
+    make
+setenv =
+    # This is just for Windows
+    # Prioritise make.bat over any make.exe which might be on PATH
+    PATHEXT=.BAT;.EXE
 basepython = python3.7
 extras = docs, mongo
 commands =
     sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_out/html" -W -bhtml
     sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_out/linkcheck" -W -blinkcheck
     sphinx-build -d "{toxworkdir}/docs_doctree" docs "{toxworkdir}/docs_out/doctest" -W -bdoctest
+    make checkchangelog
 
 [testenv:style]
 description = Stylecheck the code with black to see if anything needs changes.