[docs] Add guidance on writing changelogs

.github/PULL_REQUEST_TEMPLATE.md

@@ -18,6 +18,7 @@ Some valid responses are:
 - [ ] Format the pull request title like `[cli] Fixes bugs in 'klio job fake-cmd'`.
 - [ ] Changes are covered by unit tests (no major decrease in code coverage %) and/or integration tests.
 - [ ] Document any relevant additions/changes in the appropriate spot in `docs/src`.
+- [ ] For any change that affects users, update the package's changelog in ``docs/src/reference/<package>/changelog.rst``.
 
 
 <!---

CONTRIBUTING.rst

@@ -254,6 +254,25 @@ To view them locally
 Then navigate to ``http://localhost:8888`` in your browser.
 
 
+Changelog
+---------
+
+If your change is noteworthy, there needs to be a changelog entry so our users can learn about it!
+
+* For each pull request, add a line in ``docs/src/reference/<package>/changelog.rst`` under the appropriate section (``Added``, ``Fixed``, ``Removed``, ``Changed``, or ``Dependencies Updated``) for the latest unreleased version (e.g. ``1.2.3 (UNRELEASED)``).
+
+  * If there is no ``(UNRELEASED)`` version, start a new version section with a second-level header of ``1.2.3 (UNRELEASED)`` where ``1.2.3`` is the next anticipated release.
+  * Include links to any relevant issues, KEPs, or PRs (particularly in the case of reverts).
+
+* Wrap symbols like modules, functions, or classes into double backticks so they are rendered in a ``monospace font``.
+* If you mention functions or other callables, add parentheses at the end of their names: ``klio.func()`` or ``klio.Class.method()``. This makes the changelog a lot more readable.
+* Prefer simple past tense or constructions with "now". For example:
+
+  * Added ``klio.fun_functions.func()``.
+  * ``klio.func()`` now doesn't crash the Large Hadron Collider anymore when passed the *foobar* argument.
+
+Refer to the `changelog format <https://github.com/spotify/klio/blob/master/RELEASING.rst#changelog-format>`_ in ``RELEASING.rst`` for a complete example, and `Update Changelog <https://github.com/spotify/klio/blob/master/RELEASING.rst#update-changelog>`_ when preparing the changelog for a new release.
+
 Microsite
 ---------
 

RELEASING.rst

@@ -130,10 +130,81 @@ Releasing
 Prepare Release
 ~~~~~~~~~~~~~~~
 
-* don't forget changelog updates
-
 Before building and uploading, we need to make the required release commit(s) for a pull request.
 
+Update Changelog
+^^^^^^^^^^^^^^^^
+
+**FYI:** Each package has its changelog in ``docs/src/reference/<package>/changelog.rst``. The details of the latest release is seen on the package's PyPI project page (`for example <https://pypi.org/project/klio/>`_, see "Release Information" at the bottom).
+This is generated automatically in the package's ``setup.py::get_long_description`` function.
+
+Steps to Update
+***************
+
+1. Navigate to the package's changelog in ``docs/src/reference/<package>/changelog.rst``.
+2. There should be a header for the current version plus ``(UNRELEASED)``, e.g. ``1.2.3 (UNRELEASED)``. Update ``(UNRELEASED)`` to the package's release date, e.g. ``1.2.3 (2021-01-01)``.
+3. Make sure the changelog entries for the version are up to date. Ideally, it's all populated as contributors have added an item to the changelog along with their pull requests. If not, refer to the commits between this release and the last release for the package and populate the changelog accordingly. See `below <#changelog-format>`_ for how the changelog should be formatted. See the `Changelog section in CONTRIBUTING.rst <https://github.com/spotify/klio/blob/master/CONTRIBUTING.rst#changelog>`_ when writing an entry for a pull request when not releasing.
+4. Commit changes with the message "Prepare release <package> v1.2.3".
+
+Changelog Format
+****************
+
+1. Each changelog entry should describe the change with the users as the audience. For example, "Dropped support for Python 3.5", or "Added support for configuration templating." If the change doesn't affect the user, then it should probably not have an entry.
+
+2. Each changelog entry should fall under one of the following sections:
+
+* Added
+* Fixed
+* Removed
+* Changed
+* Dependencies Updated
+
+3. The ``changelog.rst`` file should follow the following template (note that not all sections need to have content):
+
+.. code-block:: rst
+
+    Changelog
+    =========
+
+    1.2.4 (UNRELEASED)
+    ------------------
+
+    Changed
+    *******
+
+    * ``antigravity`` submodule is now located under ``flying_pigs`` module with a redirect from the original ``frozen_hell.antigravity`` location.
+
+    Dependencies Updated
+    ********************
+
+    * Minimum version of ``teleportation`` dependency now at ``9.0.0`` due to API changes.
+
+    1.2.3 (2021-01-01)
+    ------------------
+
+    Added
+    *****
+
+    * Added support for an invisibility cloak (See `KEP 999 <https://docs.klio.io/en/latest/keps/kep-999.html>`_).
+
+    Fixed
+    *****
+
+    * Turning on flying mode now correctly detects elevation (See `PR 99999 <https://github.com/spotify/klio/pull/99999>`_).
+
+
+    1.2.2 (2020-12-01)
+    ------------------
+
+    Removed
+    *******
+
+    * Deprecated support for Python 2.9
+    * Removed unused ``nightvision`` dependency.
+
+
+Update Version
+^^^^^^^^^^^^^^
 
 **Attention:** This step should be done with the **virtualenv of the package** activated (**not** the virtualenv needed for releasing).
 This virtualenv should have the ``dev`` extras package installed, i.e. ``pip install -e ".[dev]"`` which includes the ``bumpversion`` library.

docs/src/conf.py

@@ -162,6 +162,11 @@ def find_version(*file_paths):
     r"https://github.com/spotify/klio/tree/master/docs/src/keps",
     r"https://docs.klio.io/en/latest/keps/",
 ]
+# temp ignore newly added sections to RELEASING.rst
+linkcheck_anchors_ignore = [
+    "changelog-format",
+    "update-changelog",
+]
 
 # -- Options for HTML output -------------------------------------------------