Merge pull request #2496 from oasislabs/tjanez/add-changelog

Add CHANGELOG.md and use towncrier for automatic assembly

.changelog/1845.feature.md

@@ -0,0 +1 @@
+Add `oasis-node debug storage export` sub-command.

.changelog/2377.removal.md

@@ -0,0 +1,9 @@
+Remove staking-related roothash messages.
+
+There is no longer a plan to support direct manipulation of the staking accounts
+from the runtimes in order to isolate the runtimes from corrupting the
+consensus layer.
+
+To reduce complexity, the staking-related roothash messages were removed. The
+general roothash message mechanism stayed as-is since it may be useful in the
+future, but any commits with non-empty messages are rejected for now.

.changelog/2435.feature.md

@@ -0,0 +1,2 @@
+Add `oasis-node unsafe-reset` sub-command which resets the node back to a
+freshly provisioned state, preserving any key material if it exists.

.changelog/2482.feature.md

@@ -0,0 +1,8 @@
+Add consensus block and transaction metadata accessors.
+
+In order to enable people to build "network explorers", we exposed some
+additional methods via the consensus API endpoint, specifically:
+
+- Consensus block metadata.
+- Access to raw consensus transactions within a block.
+- Stream of consensus blocks as they are finalized.

.changelog/2484.bugfix.md

@@ -0,0 +1,4 @@
+Reduce Badger in-memory cache sizes.
+
+The default is 1 GiB per badger instance and we use a few instances so this
+resulted in some nice memory usage.

.changelog/2492.removal.md

@@ -0,0 +1,4 @@
+Remove `oasis-node debug dummy` sub-commands.
+
+These are only useful for testing, and our test harness has a internal Go API
+that removes the need to have this functionality exposed as a sub-command.

.changelog/README.md

@@ -0,0 +1,93 @@
+# Change Log fragments
+
+This directory collects Change Log fragments:
+short files that each contain a snippet of MarkDown formatted text that will be
+assembled using [towncrier] to form the [Change Log] section for the next
+release.
+
+## Description
+
+A Change Log fragment should be a description of aspects of the change (if any)
+that are relevant to users.
+
+_NOTE: This could be very different from the commit message and pull request
+description, which are a description of the change as relevant to the people
+working on the code itself._
+
+The description could use one of the following two formats:
+
+- One line change summary followed by an empty line and a more detailed
+  explanation in the body.
+
+  For example:
+
+  ```text
+  Remove staking-related roothash messages.
+
+  There is no longer a plan to support direct manipulation of the staking accounts
+  from the runtimes in order to isolate the runtimes from corrupting the
+  consensus layer.
+
+  To reduce complexity, the staking-related roothash messages were removed. The
+  general roothash message mechanism stayed as-is since it may be useful in the
+  future, but any commits with non-empty messages are rejected for now.
+  ```
+
+- Shorter multi-line change description.
+
+  For example:
+
+  ```text
+  Add `oasis-node unsafe-reset` sub-command which resets the node back to a
+  freshly provisioned state, preserving any key material if it exists.
+  ```
+
+_NOTE: Don't put links to issue(s)/pull request in your text as the [towncrier]
+tool will add them automatically._
+
+## File name
+
+Each file should be named like `<ISSUE>.<TYPE>.md`, where `<ISSUE>` is a GitHub
+issue or pull request number, and `<TYPE>` is one of:
+
+- `process`: a change in Oasis Core's processes (e.g. development process,
+  release process, ...),
+- `removal`: a deprecation or removal of functionality,
+- `feature`: a new feature,
+- `bugfix`: a bug fix,
+- `doc`: a documentation-related change,
+- `trivial`: a trivial change that is _not_ included in the Change Log.
+
+For example: ``1234.feature.md`` or ``2345.bugfix.md``.
+
+If your pull requests closes an issue, use that number here.
+If there is no issue for the change you've implemented, then after you submit
+the pull request and get your pull request number, amend your commit(s) with an
+appropriately named Change Log fragment.
+
+## Render Change Log preview
+
+To get a preview of how your change (and other changes queued up in this
+directory) will look in the Change Log, install [Oasis Labs' towncrier fork]
+with:
+
+```bash
+pip3 install https://github.com/oasislabs/towncrier/archive/oasis-master.tar.gz
+```
+
+_NOTE: [towncrier] requires Python 3.5+._
+
+And then run:
+
+```bash
+towncrier build --version <NEXT-VERSION> --draft
+```
+
+replacing `<NEXT-VERSION>` with the next version of Oasis Core that this
+Change Log section is for.
+
+_NOTE: You can use any version for the preview, it doesn't really matter._
+
+[Change Log]: ../CHANGELOG.md
+[towncrier]: https://github.com/hawkowl/towncrier
+[Oasis Labs' towncrier fork]: https://github.com/oasislabs/towncrier

.changelog/template.md.j2

@@ -0,0 +1,41 @@
+{# This a Jinja2 template for preparing a new section of the Change Log with the towncrier utility.#}
+## {{ versiondata.version }} ({{ versiondata.date }})
+{% for section, _ in sections.items() %}
+
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section] %}
+{{ "### " + definitions[category]['name'] }}
+
+{% if definitions[category]['showcontent'] %}
+{% for text, values in sections[section][category].items() %}
+{% set lines = text.splitlines() %}
+{% if lines | length > 2 and lines[1] == "" %}
+- {{ lines[0] }}
+  ({{ values | join(', ') }})
+
+{{ lines[2:] | join('\n') }}
+{% else %}
+- {{ text }}
+  ({{ values | join(', ') }})
+{% endif %}
+{% if not loop.last %}
+
+{% endif %}
+{% endfor %}
+{% else %}
+- {{ sections[section][category]['']|join(', ') }}
+
+{% endif %}
+{% if sections[section][category]|length == 0 %}
+No significant changes.
+
+{% else %}
+{% endif %}
+
+{% endfor %}
+{% else %}
+No significant changes.
+
+
+{% endif %}
+{% endfor %}

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: Continuous integration
+
+on: push
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+      - name: Set up Python 3
+        uses: actions/setup-python@v1
+      - name: Install prerequisites
+        run: |
+          python -m pip install https://github.com/oasislabs/towncrier/archive/oasis-master.tar.gz
+      - name: Check for presence of a Change Log fragment
+        run: |
+          # Fetch the master branch so towncrier will be able to compare the
+          # current branch to the master branch.
+          # Source: https://github.com/actions/checkout/#fetch-all-branches.
+          git fetch --no-tags --prune --depth=1 origin +refs/heads/master:refs/remotes/origin/master
+          towncrier check

CHANGELOG.md

@@ -0,0 +1,39 @@
+# Change Log
+
+All notables changes to this project are documented in this file.
+
+The format is inspired by [Keep a Changelog].
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+
+<!-- NOTE: towncrier will not alter content above the TOWNCRIER line below. -->
+
+<!-- TOWNCRIER -->
+
+## 19.0 (2019-12-18)
+
+### Process
+
+- Start using the new Versioning and Release process for Oasis Core.
+  ([#2419](https://github.com/oasislabs/oasis-core/issues/2419))
+
+  Adopt a [CalVer](http://calver.org) (calendar versioning) scheme for Oasis
+  Core (as a whole) with the following format:
+
+  ```text
+  YY.MINOR[.MICRO][-MODIFIER]
+  ```
+
+  where:
+  - `YY` represents short year (e.g. 19, 20, 21, ...),
+  - `MINOR` represents the minor version starting with zero (e.g. 0, 1, 2, 3,
+    ...),
+  - `MICRO` represents (optional) final number in the version (sometimes
+    referred to as the "patch" segment) (e.g. 0, 1, 2, 3, ...).
+
+    If the `MICRO` version is 0, it is be omitted.
+  - `MODIFIER` represents (optional) build metadata, e.g. `git8c01382`.
+
+  The new Versioning and Release process will be described in more detail in
+  the future. For more details, see [#2457](
+  https://github.com/oasislabs/oasis-core/issues/2457).

CONTRIBUTING.md

@@ -112,6 +112,10 @@ https://github.com/oasislabs/oasis-core/blob/master/README.md).
     * Try to instrument anything that would be relevant to an operational
       network.
 
+* **Change Log:** Please write a [Change Log fragment](.changelog/README.md)
+  that will be included in the next section of the [Change Log](CHANGELOG.md)
+  once a new version is released.
+
 * **Documentation:** Please write documentation in the code as you go.
 
 * **Check CI:** Don’t break the build!

towncrier.toml

@@ -0,0 +1,16 @@
+[tool.towncrier]
+filename = "CHANGELOG.md"
+directory = ".changelog"
+issue_format = "[#{issue}](https://github.com/oasislabs/oasis-core/issues/{issue})"
+start_string = "<!-- TOWNCRIER -->\n"
+# Custom Jinja2 template for preparing a new section of the Change Log.
+template = ".changelog/template.md.j2"
+# Custom definition of Change Log fragment types.
+type = [
+  { name = "Process",                    directory = "process", showcontent = true },
+  { name = "Deprecations and Removals",  directory = "removal", showcontent = true },
+  { name = "Features",                   directory = "feature", showcontent = true },
+  { name = "Bug Fixes",                  directory = "bugfix",  showcontent = true },
+  { name = "Documentation improvements", directory = "doc",     showcontent = true },
+  { name = "Trivial Changes",            directory = "trivial", showcontent = false },
+]