From a956ccb3b0eb58ec7dfabb872d16961533a375ac Mon Sep 17 00:00:00 2001 From: Develo Date: Thu, 3 Jan 2019 20:41:31 -0300 Subject: [PATCH] Update README.md Add specific instructions for breaking changes. Fix some formatting. --- package/README.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/package/README.md b/package/README.md index 77ac795703..ac9e23de0c 100644 --- a/package/README.md +++ b/package/README.md @@ -67,12 +67,28 @@ Here is an overview of the release process. See the section below for detailed i 1. Assemble release notes. - * Since most changes are integrated into master using squash-rebase policy (i.e. one commit per PR), `git log --oneline` gives a good overview of changes in the release. + * Since most changes are integrated into master using squash-rebase policy (i.e. one commit per PR), `git log --oneline` gives a good overview of changes in the release. - * Prepare release notes in Markdown format. + * Prepare release notes in Markdown format. - * Combine related changes into the following categories, in that order: + * For changes that are breaking, duplicate those changes and put the duplicate lines into a separate group called Breaking Changes. That group should go at the top of the Changelog. The original lines for the breaking changes should be marked by appending "(Breaking change)" to the line. Example: + + ``` + Breaking Changes + ================ + API xyz changed #1234 + ... + + Library - xyz + ============= + API xyz changed #1234 (Breaking change) + ... + ``` + + + * Combine related changes into the following categories, in that order, including breaking changes with the appended mark: + - Breaking Changes - Core - *Libraries* — one section per library that received changes. If library only had a single change or a few changes, it is also okay to combine changes to a few such libraries under single "Other Libraries" entry. - Upstream dependencies @@ -116,11 +132,12 @@ The following points assume work in a direct clone of the repository, and not in 10. Create a commit to the master branch, updating: - * The version in platform.txt file. This should correspond to the version of the *next* milestone, plus `-dev` suffix. E.g. `2.5.0-dev`. + * The version in platform.txt file. This should correspond to the version of the *next* milestone, plus `-dev` suffix. E.g. `2.5.0-dev`. - * In main README.md: + * In main README.md: - - in "Latest release" section, change version number in the readthedocs link to the version which was just released, and verify that all links work. - * In doc/conf.py + - in "Latest release" section, change version number in the readthedocs link to the version which was just released, and verify that all links work. + + * In doc/conf.py - - update version and release to the *next* milestone + - update version and release to the *next* milestone