Restore Releases Changelog

Add the releases-based changelog system back, and migrate the old
changelog entries.

Signed-off-by: Hassan Abouelela <[email protected]>

11 files changed, 289 insertions, 23 deletions

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index ad10f75f..79a96ea5 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -37,7 +37,7 @@ jobs:
       - name: Generate HTML Site
         run: sphinx-build -nW -j auto -b html docs docs/build
 
-      - name: Uplaod Build Artifact
+      - name: Upload Build Artifact
         uses: actions/upload-artifact@v2
         with:
           name: docs
diff --git a/README.md b/README.md
index c6f83a08..427ab10b 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,3 @@
-# bot-core
+# bot-core ![Version]
+
+[Version]: https://img.shields.io/github/v/tag/python-discord/bot-core?label=latest&logo=version
diff --git a/docs/README.md b/docs/README.md
index fa719292..2146ce5b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -38,11 +38,11 @@ Refer to the [sphinx documentation][docstring-sections] for more information.
 Each change requires an entry in the [Changelog](./changelog.rst).
 
 Refer to the [Releases][releases] documentation for more information on the exact format and content of entries
-You can use [this site][releases] to get the PR number you'll use for your entry.
+You can use [this site][next] to get the PR number that'll be assigned for your entry.
 
 
-[next]: https://ichard26.github.io/next-pr-number/?owner=python-discord&name=bot-core
 [releases]: https://releases.readthedocs.io/en/latest/concepts.html
+[next]: https://ichard26.github.io/next-pr-number/?owner=python-discord&name=bot-core
 
 ## Static Builds
 We deploy our docs to netlify to power static previews on PRs.
diff --git a/docs/_static/changelog.css b/docs/_static/changelog.css
new file mode 100644
index 00000000..343792a1
--- /dev/null
+++ b/docs/_static/changelog.css
@@ -0,0 +1,11 @@
+[data-theme='dark'] #changelog .dark,
+[data-theme='light'] #changelog .light,
+[data-theme='auto'] #changelog .light {
+    display: inline;
+}
+
+[data-theme='dark'] #changelog .light,
+[data-theme='light'] #changelog .dark,
+[data-theme='auto'] #changelog .dark {
+    display: none;
+}
diff --git a/docs/_static/changelog.js b/docs/_static/changelog.js
new file mode 100644
index 00000000..94834eaa
--- /dev/null
+++ b/docs/_static/changelog.js
@@ -0,0 +1,41 @@
+/** Update the changelog colors in dark mode */
+function changelog_color_main() {
+    const changelog = document.getElementById("changelog");
+
+    function updateEntryColor(span) {
+        const lightColorSpan = span;
+        const darkColorSpan = lightColorSpan.cloneNode(true);
+
+        lightColorSpan.parentElement.insertBefore(darkColorSpan, lightColorSpan);
+
+        lightColorSpan.classList.add("light");
+        darkColorSpan.classList.add("dark");
+
+        let color;
+        switch (darkColorSpan.textContent) {
+            case "Feature":
+                color = "#5BF38E";
+                break;
+            case "Support":
+                color = "#55A5E7";
+                break;
+            case "Bug":
+                color = "#E14F4F";
+                break;
+            default:
+                color = lightColorSpan.style.color;
+        }
+
+        darkColorSpan.style["color"] = color;
+    }
+
+    const TYPES = ["Feature", "Bug", "Support", "Breaking"];
+
+    if (changelog !== null) {
+        Array.from(changelog.getElementsByTagName("span"))
+            .filter(value => TYPES.includes(value.textContent))
+            .forEach(updateEntryColor)
+    }
+}
+
+changelog_color_main();
diff --git a/docs/changelog.rst b/docs/changelog.rst
new file mode 100644
index 00000000..3cee3a7a
--- /dev/null
+++ b/docs/changelog.rst
@@ -0,0 +1,124 @@
+.. See docs for details on formatting your entries
+   https://releases.readthedocs.io/en/latest/concepts.html
+
+Changelog
+=========
+
+- :support:`79` Restore on-site changelog.
+
+
+- :release:`7.1.0 <24th May 2022>`
+- :feature:`78` Bump Discord.py to :literal-url:`4cbe8f5 <https://github.com/Rapptz/discord.py/tree/4cbe8f58e16f6a76371ce45a69e0832130d6d24f>`:
+
+   - This fixes a bug with permission resolution when dealing with timed out members.
+
+
+- :release:`7.0.0 <10th May 2022>`
+- :bug:`75 major` Capture all characters up to a whitespace in the Discord Invite regex.
+- :breaking:`75` Discord invite regex no longer returns a URL safe result, refer to documentation for safely handling it.
+
+
+- :release:`6.4.0 <26th April 2022>`
+- :feature:`72` Bump discord.py to :literal-url:`5a06fa5 <https://github.com/Rapptz/discord.py/tree/5a06fa5f3e28d2b7191722e1a84c541560008aea>`:
+
+   - Notably, one of the commits in this bump dynamically extends the timeout of ``Guild.chunk()`` based on the number or members, so it should actually work on our guild now.
+
+
+- :release:`6.3.2 <25th April 2022>`
+- :bug:`69` Actually use ``statsd_url`` when it gets passed to ``BotBase``.
+
+
+- :release:`6.3.1 <21st April 2022>`
+- :bug:`68` Correct version number in pyproject.toml
+
+
+- :release:`6.3.0 <21st April 2022>`
+- :feature:`-` (Committed directly to main) Don't load modules starting with ``_``
+
+
+- :release:`6.2.0 <21st April 2022>`
+- :feature:`66` Load each cog in it's own task to avoid a single cog crashing entire load process.
+
+
+- :release:`6.1.0 <20th April 2022>`
+- :feature:`65` Add ``unqualify`` to the ``botcore.utils`` namespace for use in bots that manipulate extensions.
+
+
+- :release:`6.0.0 <19th April 2022>`
+- :breaking:`64` Bump discord.py to :literal-url:`987235d <https://github.com/Rapptz/discord.py/tree/987235d5649e7c2b1a927637bab6547244ecb2cf>`:
+
+   - This reverts a change to help command behaviour that broke our custom pagination
+   - This also adds basic forum channel support to discord.py
+
+
+- :release:`5.0.4 <18th April 2022>` 63
+
+   ..
+      Feature 63 Needs to be explicitly included below because it was improperly released within a bugfix version
+      instead of a minor release
+
+- :feature:`63` Allow passing an ``api_client`` to ``BotBase.__init__`` to specify the ``botcore.site_api.APIClient`` instance to use.
+
+
+- :release:`5.0.3 <18th April 2022>`
+- :bug:`61` Reconnect to redis session on setup if it is closed.
+
+
+- :release:`5.0.2 <5th April 2022>`
+- :bug:`56` Create a dummy ``AsyncstatsdClient`` before connecting to real url, in case a connection cannot be made on init.
+- :bug:`56` Move the creation of the ``asyncio.Event``, ``BotBase._guild_available`` to within the setup hook, to avoid a deprecation notice.
+
+
+- :release:`5.0.1 <2nd April 2022>`
+- :bug:`54` Move creation of BotBase's ``aiohttp.AsyncResolver`` to the async setup hook, to avoid deprecation notice
+
+
+- :release:`5.0.0 <2nd April 2022>`
+- :breaking:`42` Remove public extensions util.
+- :feature:`42` Add ``BotBase``, a ``discord.ext.commands.Bot`` sub-class, which abstracts a lot of logic shared between our bots.
+- :feature:`42` Add async statsd client.
+- :support:`42` Bump Discord.py to latest alpha commit.
+
+
+- :release:`4.0.0 <14th March 2022>`
+- :breaking:`39` Migrate back to Discord.py 2.0.
+
+
+- :release:`3.0.1 <5th March 2022>`
+- :bug:`37` Setup log tracing when ``botcore.utils.logging`` is imported so that it can be used within botcore functions.
+
+
+- :release:`3.0.0 <3rd March 2022>`
+- :breaking:`35` Move ``apply_monkey_patches()`` directly to `botcore.utils` namespace.
+
+
+- :release:`2.1.0 <24th February 2022>`
+- :feature:`34` Port the Site API wrapper from the bot repo.
+
+
+- :release:`2.0.0 <22nd February 2022>`
+- :breaking:`35` Moved regex to ``botcore.utils`` namespace
+- :breaking:`32` Migrate from discord.py 2.0a0 to disnake.
+- :feature:`32` Add common monkey patches.
+- :feature:`29` Port many common utilities from our bots:
+
+   - caching
+   - channel
+   - extensions
+   - loggers
+   - members
+   - scheduling
+- :support:`2` Added intersphinx to docs.
+
+
+- :release:`1.2.0 <9th January 2022>`
+- :feature:`12` Code block detection regex.
+
+
+- :release:`1.1.0 <2nd December 2021>`
+- :support:`2` Autogenerated docs.
+- :feature:`2` Regex utility.
+
+
+- :release:`1.0.0 <17th November 2021>`
+- :feature:`1` Core package, poetry, and linting CI.
diff --git a/docs/conf.py b/docs/conf.py
index 8459f3fb..1cea4026 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -7,6 +7,7 @@ import sys
 from pathlib import Path
 
 import git
+import releases
 import tomli
 from sphinx.application import Sphinx
 
@@ -46,6 +47,7 @@ extensions = [
     "sphinx.ext.todo",
     "sphinx.ext.napoleon",
     "sphinx_autodoc_typehints",
+    "releases",
     "sphinx.ext.linkcode",
     "sphinx.ext.githubpages",
 ]
@@ -82,10 +84,9 @@ html_short_title = project
 html_logo = "https://raw.githubusercontent.com/python-discord/branding/main/logos/logo_full/logo_full.min.svg"
 html_favicon = html_logo
 
-html_css_files = [
-    "index.css",
-    "logo.css",
-]
+static = Path("_static")
+html_css_files = utils.get_recursive_file_uris(static, "*.css")
+html_js_files = utils.get_recursive_file_uris(static, "*.js")
 
 utils.cleanup()
 
@@ -105,6 +106,12 @@ def skip(*args) -> bool:
 def setup(app: Sphinx) -> None:
     """Add extra hook-based autodoc configuration."""
     app.connect("autodoc-skip-member", skip)
+    app.add_role("literal-url", utils.emphasized_url)
+
+    # Add a `breaking` role to the changelog
+    releases.ISSUE_TYPES["breaking"] = "F50F10"  # This is the hex for a light red color
+    releases.reorder_release_entries = utils.reorder_release_entries
+    app.add_role("breaking", releases.issues_role)
 
 
 ignored_modules = [
@@ -148,3 +155,8 @@ intersphinx_mapping = {
 
 # -- Options for the linkcode extension --------------------------------------
 linkcode_resolve = functools.partial(utils.linkcode_resolve, SOURCE_FILE_LINK)
+
+
+# -- Options for releases extension ------------------------------------------
+releases_github_path = REPO_LINK.removeprefix("https://github.com/")
+releases_release_uri = f"{REPO_LINK}/releases/tag/v%s"
diff --git a/docs/index.rst b/docs/index.rst
index 98dcd611..0a375b90 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,8 +15,9 @@ Reference
 
 .. toctree::
    :caption: Other:
+   :hidden:
 
-   Changelog <https://github.com/python-discord/bot-core/blob/main/CHANGELOG.md>
+   changelog
 
 
 Extras
@@ -25,4 +26,4 @@ Extras
 * :ref:`genindex`
 * :ref:`search`
 * :repo-file:`Information <docs/README.md>`
-* :repo-file:`Changelog <CHANGELOG.md>`
+* :doc:`changelog`
diff --git a/docs/utils.py b/docs/utils.py
index 9116c130..aaa656c3 100644
--- a/docs/utils.py
+++ b/docs/utils.py
@@ -6,6 +6,10 @@ import inspect
 import typing
 from pathlib import Path
 
+import docutils.nodes
+import docutils.parsers.rst.states
+import releases
+
 PROJECT_ROOT = Path(__file__).parent.parent
 
 
@@ -108,7 +112,7 @@ def __get_included() -> set[str]:
         try:
             module = importlib.import_module(module_name)
         except ModuleNotFoundError:
-            return {}
+            return set()
         _modules = {module.__name__ + ".rst"}
 
         if hasattr(module, "__all__"):
@@ -118,3 +122,47 @@ def __get_included() -> set[str]:
         return _modules
 
     return get_all_from_module("botcore")
+
+
+def reorder_release_entries(release_list: list[releases.Release]) -> None:
+    """
+    Sort `releases` based on `release.type`.
+
+    This is meant to be used as an override for `releases.reorder_release_entries` to support
+    custom types.
+    """
+    order = {"breaking": 0, "feature": 1, "bug": 2, "support": 3}
+    for release in release_list:
+        release["entries"].sort(key=lambda entry: order[entry.type])
+
+
+def emphasized_url(
+    name: str, rawtext: str, text: str, lineno: int, inliner: docutils.parsers.rst.states.Inliner, *__
+) -> tuple[list, list]:
+    """
+    Sphinx role to add hyperlinked literals.
+
+    ReST: :literal-url:`Google <https://google.com>`
+    Markdown equivalent: [`Google`](https://google.com)
+
+    Refer to https://docutils.sourceforge.io/docs/howto/rst-roles.html for details on the input and output.
+    """
+    arguments = text.rsplit(maxsplit=1)
+    if len(arguments) != 2:
+        message = inliner.reporter.error(
+            f"`{name}` expects a message and a URL, formatted as: :{name}:`message <url>`",
+            line=lineno
+        )
+        problem = inliner.problematic(text, rawtext, message)
+        return [problem], [message]
+
+    message, url = arguments
+    url: str = url[1:-1]  # Remove the angled brackets off the start and end
+
+    literal = docutils.nodes.literal(rawtext, message)
+    return [docutils.nodes.reference(rawtext, "", literal, refuri=url)], []
+
+
+def get_recursive_file_uris(folder: Path, match_pattern: str) -> list[str]:
+    """Get the URI of any file relative to folder which matches the `match_pattern` regex."""
+    return [file.relative_to(folder).as_posix() for file in folder.rglob(match_pattern)]
diff --git a/poetry.lock b/poetry.lock
index a6b2612e..af24501a 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -235,22 +235,21 @@ testing = ["pre-commit"]
 
 [[package]]
 name = "fakeredis"
-version = "1.7.5"
+version = "1.8"
 description = "Fake implementation of redis API for testing purposes."
 category = "main"
 optional = true
-python-versions = ">=3.7"
+python-versions = ">=3.7,<4.0"
 
 [package.dependencies]
-lupa = {version = "*", optional = true, markers = "extra == \"lua\""}
-packaging = "*"
+lupa = {version = ">=1.13,<2.0", optional = true, markers = "extra == \"lua\""}
 redis = "<=4.3.1"
-six = ">=1.12"
-sortedcontainers = "*"
+six = ">=1.16.0,<2.0.0"
+sortedcontainers = ">=2.4.0,<3.0.0"
 
 [package.extras]
-aioredis = ["aioredis"]
-lua = ["lupa"]
+aioredis = ["aioredis (>=2.0.1,<3.0.0)"]
+lua = ["lupa (>=1.13,<2.0)"]
 
 [[package]]
 name = "filelock"
@@ -769,6 +768,18 @@ hiredis = ["hiredis (>=1.0.0)"]
 ocsp = ["cryptography (>=36.0.1)", "pyopenssl (==20.0.1)", "requests (>=2.26.0)"]
 
 [[package]]
+name = "releases"
+version = "1.6.3"
+description = "A Sphinx extension for changelog manipulation"
+category = "dev"
+optional = false
+python-versions = "*"
+
+[package.dependencies]
+semantic-version = "<2.7"
+sphinx = ">=1.3"
+
+[[package]]
 name = "requests"
 version = "2.27.1"
 description = "Python HTTP for Humans."
@@ -787,6 +798,14 @@ socks = ["PySocks (>=1.5.6,!=1.5.7)", "win-inet-pton"]
 use_chardet_on_py3 = ["chardet (>=3.0.2,<5)"]
 
 [[package]]
+name = "semantic-version"
+version = "2.6.0"
+description = "A library implementing the 'SemVer' scheme."
+category = "dev"
+optional = false
+python-versions = "*"
+
+[[package]]
 name = "six"
 version = "1.16.0"
 description = "Python 2 and 3 compatibility utilities"
@@ -1059,7 +1078,7 @@ async-rediscache = ["async-rediscache"]
 [metadata]
 lock-version = "1.1"
 python-versions = "3.9.*"
-content-hash = "437a2dc7523efe2e6031432a5935451611ba427a9314bb0287f1a9cbb4466d77"
+content-hash = "b4b7d5cf3933b4237051c02050f3dadefa58ad39e5cebc7434f097b7315ea179"
 
 [metadata.files]
 aiohttp = [
@@ -1249,8 +1268,8 @@ execnet = [
     {file = "execnet-1.9.0.tar.gz", hash = "sha256:8f694f3ba9cc92cab508b152dcfe322153975c29bda272e2fd7f3f00f36e47c5"},
 ]
 fakeredis = [
-    {file = "fakeredis-1.7.5-py3-none-any.whl", hash = "sha256:c4ca2be686e7e7637756ccc7dcad8472a5e4866b065431107d7a4b7a250d4e6f"},
-    {file = "fakeredis-1.7.5.tar.gz", hash = "sha256:49375c630981dd4045d9a92e2709fcd4476c91f927e0228493eefa625e705133"},
+    {file = "fakeredis-1.8-py3-none-any.whl", hash = "sha256:65dcd78c0cd29d17daccce9f58698f6ab61ad7a404eab373fcad2b76fe8db03d"},
+    {file = "fakeredis-1.8.tar.gz", hash = "sha256:cbf8d74ae06672d40b2fa88b9ee4f1d6efd56b06b2e7f0be2c639647f00643f1"},
 ]
 filelock = [
     {file = "filelock-3.7.0-py3-none-any.whl", hash = "sha256:c7b5fdb219b398a5b28c8e4c1893ef5f98ece6a38c6ab2c22e26ec161556fed6"},
@@ -1712,10 +1731,18 @@ redis = [
     {file = "redis-4.3.1-py3-none-any.whl", hash = "sha256:84316970995a7adb907a56754d2b92d88fc2d252963dc5ac34c88f0f1a22c25d"},
     {file = "redis-4.3.1.tar.gz", hash = "sha256:94b617b4cd296e94991146f66fc5559756fbefe9493604f0312e4d3298ac63e9"},
 ]
+releases = [
+    {file = "releases-1.6.3-py2.py3-none-any.whl", hash = "sha256:cb3435ba372a6807433800fbe473760cfa781171513f670f3c4b76983ac80f18"},
+    {file = "releases-1.6.3.tar.gz", hash = "sha256:555ae4c97a671a420281c1c782e9236be25157b449fdf20b4c4b293fe93db2f1"},
+]
 requests = [
     {file = "requests-2.27.1-py2.py3-none-any.whl", hash = "sha256:f22fa1e554c9ddfd16e6e41ac79759e17be9e492b3587efa038054674760e72d"},
     {file = "requests-2.27.1.tar.gz", hash = "sha256:68d7c56fd5a8999887728ef304a6d12edc7be74f1cfa47714fc8b414525c9a61"},
 ]
+semantic-version = [
+    {file = "semantic_version-2.6.0-py3-none-any.whl", hash = "sha256:2d06ab7372034bcb8b54f2205370f4aa0643c133b7e6dbd129c5200b83ab394b"},
+    {file = "semantic_version-2.6.0.tar.gz", hash = "sha256:2a4328680073e9b243667b201119772aefc5fc63ae32398d6afafff07c4f54c0"},
+]
 six = [
     {file = "six-1.16.0-py2.py3-none-any.whl", hash = "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"},
     {file = "six-1.16.0.tar.gz", hash = "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926"},
diff --git a/pyproject.toml b/pyproject.toml
index 6c5d3c37..4ab1af72 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -43,7 +43,7 @@ Sphinx = "4.5.0"
 GitPython = "3.1.27"
 sphinx-autodoc-typehints = "1.18.1"
 furo = "2022.4.7"
-
+releases = "1.6.3"
 
 [tool.taskipy.tasks]
 lint = "pre-commit run --all-files"