Remove unreleased.rst (digital-asset#3547)

* Start working on getting rid of unreleased.rst Document new process in CONTRIBUTING.md, .github/pull_request_template.md and unreleased.rst (for good measure) Report the previous changelog additions here so that they're not lost in the mist of times. CHANGELOG_BEGIN - [DAML Stdlib] Added the ``NumericScale`` typeclass, which improves the type inference for Numeric literals, and helps catch the creation of out-of-bound Numerics earlier in the compilation process. - [DAML Triggers] ``emitCommands`` now accepts an additional argument that allows you to mark contracts as pending. Those contracts will be automatically filtered from the result of ``getContracts`` until we receive the corresponding completion/transaction. - [Navigator] Fixed a bug where Navigator becomes unresponsive if the ledger does not contain any DAML packages. - [Ledger-API] Add field ``gen_map`` in Protobuf definition for ledger api values. This field is used to support generic maps, an new feature currently in development. See issue digital-asset#3356 for more details about generic maps. The Ledger API will send no messages where this field is set, when using a stable version of DAML-LF. However the addition of this field may cause pattern-matching exhaustive warnings in the code of ledger API clients. Those warnings can be safely ignored until GenMap is made stable in an upcoming version of DAML-LF. - [JSON API - Experimental] CLI configuration to enable serving static content as part of the JSON API daemon: ``--static-content "directory=/full/path,prefix=static"`` This configuration is NOT recommended for production deployment. See issue digital-asset#2782. - [Extractor] The app can now work against a Ledger API server that requires client authentication. See `issue digital-asset#3157 <https://github.com/digital-asset/daml/issues/3157>`__. - [DAML Script] This release contains a first version of an experimental DAML script feature that provides a scenario-like API that is run against an actual ledger. - [DAML Compiler] The default DAML-LF version is now 1.7. You can still produce DAML-LF 1.6 by passing ``--target=1.6`` to ``daml build``. - [JSON API - Experimental] The database schema has changed; if using ``--query-store-jdbc-config``, you must rebuild the database by adding ``,createSchema=true``. See `issue digital-asset#3461 <https://github.com/digital-asset/daml/pull/3461>`_. - [JSON API - Experimental] Terminate process immediately after creating schema. See issue digital-asset#3386. - [DAML Stdlib] ``fromAnyChoice`` and ``fromAnyContractKey`` now take the template type into account. CHANGELOG_END * Document new release process to gather changelog additions * Change the release script to ignore unreleased.rst * Remove spurious unreleased.rst lines * Transition to use tags * Document new way to get changelog additions with tags * Update release/RELEASE.md Co-Authored-By: Gary Verhaegen <gary.verhaegen@digitalasset.com> * Address digital-asset#3547 (comment) * Document correction process * Add copyright header to unreleased.sh * Update CONTRIBUTING.md Co-Authored-By: Gary Verhaegen <gary.verhaegen@digitalasset.com> * Modify CONTRIBUTING.md after @garyverhaegen-da's proposal * Make unreleased.sh run per commit and treat tags as case-insensitive * Fix documentation for replacements
FlashSheridan · Nov 20, 2019 · 84e6064 · 84e6064
1 parent c501866
commit 84e6064
Show file tree

Hide file tree

Showing 7 changed files with 69 additions and 60 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -1,3 +1 @@
-unreleased.rst merge=union
-
 *.daml linguist-language=Haskell
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -4,7 +4,7 @@
 - [ ] Include appropriate tests
 - [ ] Set a descriptive title and thorough description
 - [ ] Add a reference to the [issue this PR will solve](https://github.com/digital-asset/daml/issues), if appropriate
-- [ ] Add a line to the [release notes](https://github.com/digital-asset/daml/blob/master/unreleased.rst), if appropriate
+- [ ] Include changelog additions in one or more commit message bodies between the `CHANGELOG_BEGIN` and `CHANGELOG_END` tags, if appropriate
 - [ ] Normal production system change, include purpose of change in description
 
 NOTE: CI is not automatically run on non-members pull-requests for security

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -30,11 +30,32 @@ For Git commit messages, our principle is that `git log --pretty=oneline` should
 - Does your PR include appropriate tests?
 - Make sure your PR title and description makes it easy for other developers to understand what the contained commits do. The title should say what the changes do. The description should expand on what it does (if not obvious from the title alone), and say why it is being done.
 - If your PR corresponds to an issue, add “Fixes #XX” to your pull request description. This will auto-close the corresponding issue when the commit is merged into master and tie the PR to the issue.
-- If your PR includes user-facing changes, you must add a line describing the change to [unreleased.rst](unreleased.rst) as part of your PR. Each entry in this document must start with the component to which is belongs, as in the following example:
+- If your PR includes user-facing changes, the squashed commit for the PR must include in its body a section between the ``CHANGELOG_BEGIN`` and ``CHANGELOG_END`` tags that includes relevant changelog entries, where each entry starts with the component to which it belongs in square brackets. Use RST to format links as this text will be added to the changelog upon release.
+
+The following is an example of a well-formed commit, including the description (first line) and a body that includes changelog additions:
+
+      Fixes #1311
+
+      Also fixes a typo in the Scala bindings documentation.
+
+      CHANGELOG_BEGIN
 
       - [Sandbox] Introduced a new API for package management.
         See `#1311 <https://github.com/digital-asset/daml/issues/1311>`__.
 
+      CHANGELOG_END
+
+If you want to amend an existing changelog entry part of a PR already merged on master, do so by adding a ``WARNING`` to your changelog additions:
+
+      CHANGELOG_BEGIN
+
+      WARNING: replace existing changelog entry "Introduced a new API for package management" with the following.
+
+      - [Sandbox] Introduce a new API for party management.
+      See `#1311 <https://github.com/digital-asset/daml/issues/1311>`__.
+
+      CHANGELOG_END
+
 ## Working with issues
 
 We use issues and [pull requests](https://help.github.com/articles/about-pull-requests/) to collaborate and track our work. Anyone is welcome to open an issue. If you just want to ask a question, please ask away on [Stack Overflow](https://stackoverflow.com/questions/tagged/daml) using the tag `daml`.

diff --git a/release/RELEASE.md b/release/RELEASE.md
@@ -3,12 +3,27 @@
 1. Make a PR that bumps the version number in the `VERSION`
    file and adds a new header and label for the new version in
    `docs/source/support/release-notes.rst` (see previous releases as examples).
-   Release notes should be cut and pasted under the new header from `unreleased.rst`.
-   Each change outlined in `unreleased.rst` is preceded by the section to
+   Release notes additions can be retrieved from commits using the following command:
+
+     ./unreleased.sh <revision range>
+
+   where `<revision range>` is the expressions (documented under `man gitrevisions`) to only read the relevant commits since the last release.
+   If, for example, the previous release is tagged as `v0.13.36` the `<revision range>` for all commits since then is `v0.13.36..`.
+   Each change outlined by the output of this command is preceded by the section to
    which it belongs: create one entry per section and add all pertaining
    items (without the section tag) to the release notes.
-   It is important that the PR only changes `VERSION`, `release-notes.rst` and `unreleased.rst`.
-   Note that `unreleased.rst` and `release-notes.rst` must be modified even if
+   Note that the changelog may also specify edits to existing changelog additions, in which case they will be reported with the `WARNING` tag as in the following example:
+
+       CHANGELOG_BEGIN
+
+       WARNING: fix typo in entry "Adds new amdin API to upload DAR files" with the following.
+
+       - [Sandbox] Adds new admin API to upload DAR files
+
+       CHANGELOG_END
+
+   It is important that the PR only changes `VERSION`, `release-notes.rst`.
+   Note that `VERSION` and `release-notes.rst` must be modified even if
    there have been no changes that have been added to the release notes so far.
 1. Merge the PR.
 1. Once CI has passed for the corresponding master build, the release should be

diff --git a/release/src/Util.hs b/release/src/Util.hs
@@ -444,11 +444,10 @@ isReleaseCommit :: MonadCI m => m Bool
 isReleaseCommit = do
     files <- gitChangedFiles "HEAD"
     let isRelease = "VERSION" `elem` files
-                 && "unreleased.rst" `elem` files
                  && "docs/source/support/release-notes.rst" `elem` files
-                 && length files == 3
+                 && length files == 2
     if "VERSION" `elem` files && not isRelease
-    then throwIO $ CIException "Release commit should only change VERSION, release-notes.rst and unreleased.rst."
+    then throwIO $ CIException "Release commit should only change VERSION and release-notes.rst"
     else return isRelease
 
 runFastLoggingT :: LoggingT IO c -> IO c

diff --git a/unreleased.rst b/unreleased.rst
@@ -1,52 +1,23 @@
 .. Copyright (c) 2019 The DAML Authors. All rights reserved.
 .. SPDX-License-Identifier: Apache-2.0
 
-Release notes
-#############
-
-This page contains release notes for the SDK.
-
-HEAD — ongoing
---------------
-
-- [DAML Stdlib] Added the ``NumericScale`` typeclass, which improves the type inference for Numeric literals, and helps catch the creation of out-of-bound Numerics earlier in the compilation process.
-
-- [DAML Triggers] ``emitCommands`` now accepts an additional argument
-  that allows you to mark contracts as pending. Those contracts will
-  be automatically filtered from the result of ``getContracts`` until
-  we receive the corresponding completion/transaction.
-
-- [Navigator] Fixed a bug where Navigator becomes unresponsive if the ledger does not contain any DAML packages.
-
-- [Ledger-API] Add field ``gen_map`` in Protobuf definition for ledger
-  api values. This field is used to support generic maps, an new
-  feature currently in development.  See issue
-  https://github.com/digital-asset/daml/pull/3356 for more details
-  about generic maps.
-
-  The Ledger API will send no messages where this field is set, when
-  using a stable version of DAML-LF.  However the addition of this
-  field may cause pattern-matching exhaustive warnings in the code of
-  ledger API clients. Those warnings can be safely ignored until
-  GenMap is made stable in an upcoming version of DAML-LF.
-
-- [JSON API - Experimental] CLI configuration to enable serving static content as part of the JSON API daemon:
-  ``--static-content "directory=/full/path,prefix=static"``
-  This configuration is NOT recommended for production deployment. See issue #2782.
-
-- [Extractor] The app can now work against a Ledger API server that requires client authentication. See `issue #3157 <https://github.com/digital-asset/daml/issues/3157>`__.
-- [DAML Script] This release contains a first version of an experimental DAML script
-   feature that provides a scenario-like API that is run against an actual ledger.
-- [DAML Compiler] The default DAML-LF version is now 1.7. You can
-  still produce DAML-LF 1.6 by passing ``--target=1.6`` to ``daml
-  build``.
-
-- [JSON API - Experimental] The database schema has changed; if using
-  ``--query-store-jdbc-config``, you must rebuild the database by adding
-  ``,createSchema=true``.
-  See `issue #3461 <https://github.com/digital-asset/daml/pull/3461>`_.
-
-- [JSON API - Experimental] Terminate process immediately after creating schema. See issue #3386.
-
-- [DAML Stdlib] ``fromAnyChoice`` and ``fromAnyContractKey`` now take
-  the template type into account.
+WARNING: THIS FILE IS NO LONGER USED AND WILL SOON BE DELETED!
+
+Changelog additions must now be added to the end of one or more commit message bodies in a PR.
+
+The following is an example of a commit message including a description and a body that includes changelog additions:
+
+.. code-block:: none
+
+  Fixes #1311
+
+  Also fixes a typo in the Scala bindings documentation.
+
+  CHANGELOG_BEGIN
+
+  - [Sandbox] Introduced a new API for package management.
+    See `#1311 <https://github.com/digital-asset/daml/issues/1311>`__.
+
+  CHANGELOG_END
+
+Please check `CONTRIBUTING.MD <https://github.com/digital-asset/daml/blob/master/CONTRIBUTING.md#pull-request-checklist>`__ for more details.
diff --git a/unreleased.sh b/unreleased.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Copyright (c) 2019 The DAML Authors. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+for SHA in $(git log --format=%H "$1"); do git show --format=%b "$SHA" | awk '/^$/{next} toupper($0) ~ /CHANGELOG_END/{flag=0; next} toupper($0) ~ /CHANGELOG_BEGIN/{flag=1; next} flag'; done
Original file line number	Diff line number	Diff line change
		@@ -1,3 +1 @@
		unreleased.rst merge=union

		*.daml linguist-language=Haskell