From d4b6fdea92181429758a8d3477baf76302ed734f Mon Sep 17 00:00:00 2001 From: Michael H Date: Tue, 16 Jul 2019 21:12:43 -0400 Subject: [PATCH] Add towncrier (#2873) * Adds towncrier as our changelog system. * Updates our contributor guidelines for this. Resolves #2872 --- .github/CONTRIBUTING.md | 37 +++++++-- Makefile | 5 ++ changelog.d/.gitignore | 1 + changelog.d/2872.feature.rst | 1 + changelog.d/admin/.gitignore | 1 + changelog.d/alias/.gitignore | 1 + changelog.d/audio/.gitignore | 1 + changelog.d/bank/.gitignore | 1 + changelog.d/cleanup/.gitignore | 1 + changelog.d/customcom/.gitignore | 1 + changelog.d/downloader/.gitignore | 1 + changelog.d/economy/.gitignore | 1 + changelog.d/filter/.gitignore | 1 + changelog.d/general/.gitignore | 1 + changelog.d/image/.gitignore | 1 + changelog.d/mod/.gitignore | 1 + changelog.d/modlog/.gitignore | 1 + changelog.d/mutes/.gitignore | 1 + changelog.d/permissions/.gitignore | 1 + changelog.d/reports/.gitignore | 1 + changelog.d/streams/.gitignore | 1 + changelog.d/trivia/.gitignore | 1 + changelog.d/warnings/.gitignore | 1 + make.bat | 6 ++ pyproject.toml | 125 +++++++++++++++++++++++++++++ setup.cfg | 1 + tools/check_changelog_entries.sh | 19 +++++ tools/primary_deps.ini | 1 + tox.ini | 6 ++ 29 files changed, 215 insertions(+), 6 deletions(-) create mode 100644 changelog.d/.gitignore create mode 100644 changelog.d/2872.feature.rst create mode 100644 changelog.d/admin/.gitignore create mode 100644 changelog.d/alias/.gitignore create mode 100644 changelog.d/audio/.gitignore create mode 100644 changelog.d/bank/.gitignore create mode 100644 changelog.d/cleanup/.gitignore create mode 100644 changelog.d/customcom/.gitignore create mode 100644 changelog.d/downloader/.gitignore create mode 100644 changelog.d/economy/.gitignore create mode 100644 changelog.d/filter/.gitignore create mode 100644 changelog.d/general/.gitignore create mode 100644 changelog.d/image/.gitignore create mode 100644 changelog.d/mod/.gitignore create mode 100644 changelog.d/modlog/.gitignore create mode 100644 changelog.d/mutes/.gitignore create mode 100644 changelog.d/permissions/.gitignore create mode 100644 changelog.d/reports/.gitignore create mode 100644 changelog.d/streams/.gitignore create mode 100644 changelog.d/trivia/.gitignore create mode 100644 changelog.d/warnings/.gitignore create mode 100644 pyproject.toml create mode 100644 tools/check_changelog_entries.sh diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 308b1d4ec..5dc471615 100644 --- a/.github/CONTRIBUTING.md +++ b/.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.8 How To Suggest A Feature Or Enhancement](#48-how-to-suggest-a-feature-or-enhancement) + * [4.7 Using towncrier](#47-using-towncrier) + * [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 `. ### 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. diff --git a/Makefile b/Makefile index a39d615e7..5d9afbf64 100644 --- a/Makefile +++ b/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 diff --git a/changelog.d/.gitignore b/changelog.d/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/2872.feature.rst b/changelog.d/2872.feature.rst new file mode 100644 index 000000000..d4e20a46a --- /dev/null +++ b/changelog.d/2872.feature.rst @@ -0,0 +1 @@ +Red now uses towncrier for changelog generation \ No newline at end of file diff --git a/changelog.d/admin/.gitignore b/changelog.d/admin/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/admin/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/alias/.gitignore b/changelog.d/alias/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/alias/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/audio/.gitignore b/changelog.d/audio/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/audio/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/bank/.gitignore b/changelog.d/bank/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/bank/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/cleanup/.gitignore b/changelog.d/cleanup/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/cleanup/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/customcom/.gitignore b/changelog.d/customcom/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/customcom/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/downloader/.gitignore b/changelog.d/downloader/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/downloader/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/economy/.gitignore b/changelog.d/economy/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/economy/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/filter/.gitignore b/changelog.d/filter/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/filter/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/general/.gitignore b/changelog.d/general/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/general/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/image/.gitignore b/changelog.d/image/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/image/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/mod/.gitignore b/changelog.d/mod/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/mod/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/modlog/.gitignore b/changelog.d/modlog/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/modlog/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/mutes/.gitignore b/changelog.d/mutes/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/mutes/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/permissions/.gitignore b/changelog.d/permissions/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/permissions/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/reports/.gitignore b/changelog.d/reports/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/reports/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/streams/.gitignore b/changelog.d/streams/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/streams/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/trivia/.gitignore b/changelog.d/trivia/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/trivia/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelog.d/warnings/.gitignore b/changelog.d/warnings/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/changelog.d/warnings/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/make.bat b/make.bat index 7f9b79df6..46ea86173 100644 --- a/make.bat +++ b/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 ^ diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 000000000..0b98577f9 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,125 @@ +[tool.towncrier] + package = "redbot" + filename = "CHANGELOG.rst" + directory = "changelog.d" + issue_format = "`#{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 diff --git a/setup.cfg b/setup.cfg index 6f1c51690..399c55186 100644 --- a/setup.cfg +++ b/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 diff --git a/tools/check_changelog_entries.sh b/tools/check_changelog_entries.sh new file mode 100644 index 000000000..34da49ba1 --- /dev/null +++ b/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 diff --git a/tools/primary_deps.ini b/tools/primary_deps.ini index f35aa103c..390920480 100644 --- a/tools/primary_deps.ini +++ b/tools/primary_deps.ini @@ -30,6 +30,7 @@ docs = Sphinx sphinx_rtd_theme sphinxcontrib-trio + towncrier mongo = dnspython motor diff --git a/tox.ini b/tox.ini index c61cb7091..965ea3e99 100644 --- a/tox.ini +++ b/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.