diff --git a/.gitattributes b/.gitattributes index 4c2ee0eb89..9a7b748782 100644 --- 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 index 8389496875..11bb4f8f9a 100644 --- 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 index c2a7bdf5ee..b4e481f18f 100644 --- 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 `__. + 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 `__. + + 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 index ff715f0cfd..56f637e7f9 100644 --- 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 + + where `` 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 `` 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 index f053b4046e..5f395becdc 100644 --- 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 index 54a8eed575..cb92b18fb8 100644 --- 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 -############# +WARNING: THIS FILE IS NO LONGER USED AND WILL SOON BE DELETED! -This page contains release notes for the SDK. +Changelog additions must now be added to the end of one or more commit message bodies in a PR. -HEAD — ongoing --------------- +The following is an example of a commit message including a description and a body that includes changelog additions: -- [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. +.. code-block:: none -- [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. + Fixes #1311 - 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. + Also fixes a typo in the Scala bindings documentation. -- [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. + CHANGELOG_BEGIN -- [Extractor] The app can now work against a Ledger API server that requires client authentication. See `issue #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``. + - [Sandbox] Introduced a new API for package management. + See `#1311 `__. -- [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 `_. + CHANGELOG_END -- [JSON API - Experimental] Terminate process immediately after creating schema. See issue #3386. - -- [DAML Stdlib] ``fromAnyChoice`` and ``fromAnyContractKey`` now take - the template type into account. +Please check `CONTRIBUTING.MD `__ for more details. diff --git a/unreleased.sh b/unreleased.sh new file mode 100755 index 0000000000..69f8a547ce --- /dev/null +++ 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