From 1fd0052aa05c7b173a6a699f0a5a00b9de882b73 Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Mon, 21 Sep 2020 10:54:21 +0100 Subject: [PATCH 1/9] clean up package naming and versioning --- text/0079-cdk-2.0.md | 51 ++++++++++++++++++++++---------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 33e6016d8..4f90c3cf5 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -141,31 +141,7 @@ following changes will be made right away: 1. the `monocdk-experiment` package will be renamed to `aws-cdk-lib` A continuous integration pipeline will be configured on this new branch, so that pull requests can be automatically -validated. Releases will be automatically published, however using the `next` NPM distribution tag instead of `latest`. - -> Other package managers we target (NuGet, Maven Central, PyPI) do not have a feature similar to NPM distribution tags. -> In those, the version number is the only mechanism to signal pre-releases. To this effect, the version numbers used -> must adhere to the correct local convension (which can be achieved using the existing version suffix features of -> `jsii-pacmak`): -> -> - **NuGet** [honors prerelease identifiers][nuget-versioning] in a way that is compatible with [Semantic Versioning]. -> Using the same version number as the NPM package will result in the correct behavior. The standard behavior of -> `nuget` is to resolve to the _latest stable release_, while resolving to pre-releases requires the user to use a -> pre-release identifier in their dependency specifications. -> - **Maven Central** uses the `-SNAPSHOT` suffix to version numbers to denote versions that are in active development. -> Publishing `SNAPSHOT` involves using a `SNAPSHOT`-specific repository. _Maven Central_ offers a _SNAPSHOT_ -> repository (at `https://oss.sonatype.org/content/repositories/snapshots`), which can be used. In order to install -> `SNAPSHOT` releases, customers must manually enable the `SNAPSHOT` repository in their configuration. -> - **PyPI** uses a specific set of version suffixes to identify pre-releases (`.dev#` for development releases, `.a#` -> for alphas, `.b#` for betas, and `.rc#` for release candidates). Modern package installers ignore pre-releases by -> default. -> -> For **NuGet** and **Maven Central**, the [GitHub Packages] registry could be used as an alternate or additional -> location where customers would consume pre-releases from. - -[semantic versioning]: https://semver.org -[nuget-versioning]: https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#pre-release-versions -[github packages]: https://github.com/features/packages +validated. As long as the codebases have not diverged too much, it should be possible to continue forward-porting new developments on top of the `v2` branch by simply cherry-picking new commits from the `master` branch. Alternatively, it might be @@ -200,6 +176,31 @@ auditable by users, who will naturally retain the ability to opt out of this fea [version reporting]: https://docs.aws.amazon.com/cdk/latest/guide/cli.html#version_reporting +## Releasing to Package Managers + +`aws-cdk-lib` will be released to the various package managers under the following package name. + +| Github & NPM | Maven Central | PyPI | NuGet | +| -- | -- | -- | -- | +| `aws-cdk-lib` | `software.amazon.awscdk.lib` | `aws-cdk.lib` | `Amazon.CDK.Lib` | + +CDKv2 will be published in three phases - **alpha**, **developer preview** and finally **generally available**. +The following table describes the versioning scheme in the different package managers across the different phases. + +| | Github & NPM | Maven Central | PyPI | NuGet | +| -- | -- | -- | -- | -- | +| **Spec** | [semantic versioning] | TBD
(`-SNAPSHOT` ?) | [python packaging] | [nuget versioning] | +| **Alpha** | `2.0.0-alpha.1`
`2.0.0-alpha.2` | TBD | `2.0.0.a1`
`2.0.0.a2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | +| **Dev Preview** | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | TBD | `2.0.0.dev1`
`2.0.0.dev2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | +| **GA** | `2.0.0`
`2.0.1` | `2.0.0`
`2.0.1` | `2.0.0`
`2.0.1` | `2.0.0`
`2.0.1` | `2.0.0`
`2.0.1` | + +Besides the pre-releases suffix, NPM releases during the alpha and developer preview phases will also include a `v2` +distribution tag. + +[semantic versioning]: https://semver.org/#spec-item-9 +[nuget versioning]: https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#pre-release-versions +[python packaging]: https://packaging.python.org/guides/distributing-packages-using-setuptools/#pre-release-versioning + ## Feature Implementation This section provides detailed plans for implementing the features that were scoped in for this new major version. From 1438be844617fefe820f52fc312149858cc3a5ae Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Mon, 21 Sep 2020 10:57:02 +0100 Subject: [PATCH 2/9] TOC updates --- text/0079-cdk-2.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 4f90c3cf5..d5b897f7e 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -106,6 +106,8 @@ The development and release of v2 will be done in several key steps, detailed in 1. [Preliminary work in v1](#preliminary-work-in-v1) 1. [Create a v2 development branch by forking v1](#forking-v2-out-of-v1) +1. [Monolithic Packaging](#monolithic-packaging) +1. [Package Managers](#releasing-to-package-managers) 1. [Make the necessary code changes to implement all features scoped in for v2](#feature-implementation) 1. [Prepare documentation updates](#documentation-updates) 1. [Announce availability of an _experimental_ pre-releases to the usual package registries](#prerelease-announcement) From d04b348050ebb906d975b8ee10303586c28ab9be Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Mon, 21 Sep 2020 11:12:18 +0100 Subject: [PATCH 3/9] allow br in markdown files --- tools/linters/markdownlint.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tools/linters/markdownlint.json b/tools/linters/markdownlint.json index af6c2c67d..abb3220b4 100644 --- a/tools/linters/markdownlint.json +++ b/tools/linters/markdownlint.json @@ -11,8 +11,9 @@ }, "no-inline-html": { "allowed_elements": [ - "span", + "br", "details", + "span", "summary" ] }, From a0e33d015ba23ec04f60eb3e719be9da31887cdd Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Mon, 21 Sep 2020 14:56:50 +0100 Subject: [PATCH 4/9] maven --- text/0079-cdk-2.0.md | 9 +++++---- tools/linters/markdownlint.json | 3 ++- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index d5b897f7e..ba0d9283b 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -191,15 +191,16 @@ The following table describes the versioning scheme in the different package man | | Github & NPM | Maven Central | PyPI | NuGet | | -- | -- | -- | -- | -- | -| **Spec** | [semantic versioning] | TBD
(`-SNAPSHOT` ?) | [python packaging] | [nuget versioning] | -| **Alpha** | `2.0.0-alpha.1`
`2.0.0-alpha.2` | TBD | `2.0.0.a1`
`2.0.0.a2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | -| **Dev Preview** | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | TBD | `2.0.0.dev1`
`2.0.0.dev2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | -| **GA** | `2.0.0`
`2.0.1` | `2.0.0`
`2.0.1` | `2.0.0`
`2.0.1` | `2.0.0`
`2.0.1` | `2.0.0`
`2.0.1` | +| **Spec** | [semantic versioning] | [pom version order] | [python packaging] | [nuget versioning] | +| **Alpha** | `2.0.0-alpha.1`
`2.0.0-alpha.2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | `2.0.0.a1`
`2.0.0.a2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | +| **Dev Preview** | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | `2.0.0.dev1`
`2.0.0.dev2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | +| **GA** | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | Besides the pre-releases suffix, NPM releases during the alpha and developer preview phases will also include a `v2` distribution tag. [semantic versioning]: https://semver.org/#spec-item-9 +[pom version order]: https://maven.apache.org/pom.html#Version_Order_Specification [nuget versioning]: https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#pre-release-versions [python packaging]: https://packaging.python.org/guides/distributing-packages-using-setuptools/#pre-release-versioning diff --git a/tools/linters/markdownlint.json b/tools/linters/markdownlint.json index abb3220b4..4c62fd4d6 100644 --- a/tools/linters/markdownlint.json +++ b/tools/linters/markdownlint.json @@ -4,7 +4,8 @@ "fenced-code-language": false, "first-line-h1": false, "line_length": { - "line_length": 150 + "line_length": 150, + "tables": false }, "no-duplicate-heading": { "siblings_only": true From 79d960ac53dfbee2302a2478a4cdc794af0cac30 Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Mon, 21 Sep 2020 15:00:01 +0100 Subject: [PATCH 5/9] adjust python versioning --- text/0079-cdk-2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index ba0d9283b..f63611619 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -193,7 +193,7 @@ The following table describes the versioning scheme in the different package man | -- | -- | -- | -- | -- | | **Spec** | [semantic versioning] | [pom version order] | [python packaging] | [nuget versioning] | | **Alpha** | `2.0.0-alpha.1`
`2.0.0-alpha.2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | `2.0.0.a1`
`2.0.0.a2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | -| **Dev Preview** | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | `2.0.0.dev1`
`2.0.0.dev2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | +| **Dev Preview** | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | `2.0.0.rc1`
`2.0.0.rc2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | | **GA** | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | Besides the pre-releases suffix, NPM releases during the alpha and developer preview phases will also include a `v2` From 75dc7f87622ecdb601ac2f8c0340a04aeb48ef0f Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Mon, 21 Sep 2020 15:08:27 +0100 Subject: [PATCH 6/9] some explanation --- text/0079-cdk-2.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index f63611619..82539d8d0 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -187,6 +187,8 @@ auditable by users, who will naturally retain the ability to opt out of this fea | `aws-cdk-lib` | `software.amazon.awscdk.lib` | `aws-cdk.lib` | `Amazon.CDK.Lib` | CDKv2 will be published in three phases - **alpha**, **developer preview** and finally **generally available**. +During the first two phases, packages will be published with the base version of `2.0.0` and every release will use a +sequentially increasing pre-release identifier. The following table describes the versioning scheme in the different package managers across the different phases. | | Github & NPM | Maven Central | PyPI | NuGet | From bd6bddf3196d8d3fc0e62a1f4639ba380c705913 Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Tue, 22 Sep 2020 14:13:49 +0100 Subject: [PATCH 7/9] fixup python naming --- text/0079-cdk-2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 82539d8d0..0bab6776d 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -184,7 +184,7 @@ auditable by users, who will naturally retain the ability to opt out of this fea | Github & NPM | Maven Central | PyPI | NuGet | | -- | -- | -- | -- | -| `aws-cdk-lib` | `software.amazon.awscdk.lib` | `aws-cdk.lib` | `Amazon.CDK.Lib` | +| `aws-cdk-lib` | `software.amazon.awscdk.lib` | `aws-cdk-lib` | `Amazon.CDK.Lib` | CDKv2 will be published in three phases - **alpha**, **developer preview** and finally **generally available**. During the first two phases, packages will be published with the base version of `2.0.0` and every release will use a From a0fca072de37298973a92572bd71b1652fc72d05 Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Tue, 22 Sep 2020 17:02:15 +0100 Subject: [PATCH 8/9] release candidate & ascii tables --- text/0079-cdk-2.0.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 0bab6776d..73e95b905 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -182,21 +182,21 @@ auditable by users, who will naturally retain the ability to opt out of this fea `aws-cdk-lib` will be released to the various package managers under the following package name. -| Github & NPM | Maven Central | PyPI | NuGet | -| -- | -- | -- | -- | +| Github & NPM | Maven Central | PyPI | NuGet | +| ------------- | ---------------------------- | ------------- | ---------------- | | `aws-cdk-lib` | `software.amazon.awscdk.lib` | `aws-cdk-lib` | `Amazon.CDK.Lib` | -CDKv2 will be published in three phases - **alpha**, **developer preview** and finally **generally available**. +CDKv2 will be published in three phases - **alpha**, **release candidate** and finally **generally available**. During the first two phases, packages will be published with the base version of `2.0.0` and every release will use a sequentially increasing pre-release identifier. The following table describes the versioning scheme in the different package managers across the different phases. -| | Github & NPM | Maven Central | PyPI | NuGet | -| -- | -- | -- | -- | -- | -| **Spec** | [semantic versioning] | [pom version order] | [python packaging] | [nuget versioning] | -| **Alpha** | `2.0.0-alpha.1`
`2.0.0-alpha.2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | `2.0.0.a1`
`2.0.0.a2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | -| **Dev Preview** | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | `2.0.0-devpreview.1`
`2.0.0-devpreview.2` | `2.0.0.rc1`
`2.0.0.rc2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | -| **GA** | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | +| | Github & NPM | Maven Central | PyPI | NuGet | +| ---------------- | ------------------------------------- | ------------------------------------- | ----------------------------- | ------------------------------------- | +| **Spec** | [semantic versioning] | [pom version order] | [python packaging] | [nuget versioning] | +| **Alpha** | `2.0.0-alpha.1`
`2.0.0-alpha.2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | `2.0.0.a1`
`2.0.0.a2` | `2.0.0-alpha.1`
`2.0.0-alpha.2` | +| **DevPreview** | `2.0.0-rc.1`
`2.0.0-rc.2` | `2.0.0-rc.1`
`2.0.0-rc.2` | `2.0.0.rc1`
`2.0.0.rc2` | `2.0.0-rc.1`
`2.0.0-rc.2` | +| **GA** | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | Besides the pre-releases suffix, NPM releases during the alpha and developer preview phases will also include a `v2` distribution tag. From e8d7f371666c16fbc3b092121cbef1228454eec7 Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Wed, 23 Sep 2020 11:07:51 +0100 Subject: [PATCH 9/9] expanded dist tags --- text/0079-cdk-2.0.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 73e95b905..ace25adb2 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -199,7 +199,12 @@ The following table describes the versioning scheme in the different package man | **GA** | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | `2.0.0`
`2.1.0` | Besides the pre-releases suffix, NPM releases during the alpha and developer preview phases will also include a `v2` -distribution tag. +distribution tag. During these two phases, the `latest` distribution tag will continue to track the latest version of +CDKv1, i.e., `1.x.y`. + +When CDKv2 is declared GA, the `v2` distribution tag will be updated once to match the first GA release, and the +`latest` distribution tag will start tracking the versions of CDKv2. A new distribution tag called `v1` will be +created to track the latest release of CDK `1.x.y`. [semantic versioning]: https://semver.org/#spec-item-9 [pom version order]: https://maven.apache.org/pom.html#Version_Order_Specification