rfc 79: cdkv2.0 - release & versioning

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)
@@ -141,31 +143,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 +178,39 @@ 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**, **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` <br/> `2.0.0-alpha.2` | `2.0.0-alpha.1` <br/> `2.0.0-alpha.2` |  `2.0.0.a1` <br/> `2.0.0.a2`  | `2.0.0-alpha.1` <br/> `2.0.0-alpha.2` |
+|  **DevPreview**  |    `2.0.0-rc.1` <br/> `2.0.0-rc.2`    |    `2.0.0-rc.1` <br/> `2.0.0-rc.2`    | `2.0.0.rc1` <br/> `2.0.0.rc2` |    `2.0.0-rc.1` <br/> `2.0.0-rc.2`    |
+|      **GA**      |         `2.0.0` <br/> `2.1.0`         |         `2.0.0` <br/> `2.1.0`         |     `2.0.0` <br/> `2.1.0`     |         `2.0.0` <br/> `2.1.0`         |
+
+Besides the pre-releases suffix, NPM releases during the alpha and developer preview phases will also include a `v2`
+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
+[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.

tools/linters/markdownlint.json

@@ -4,15 +4,17 @@
   "fenced-code-language": false,
   "first-line-h1": false,
   "line_length": {
-    "line_length": 150
+    "line_length": 150,
+    "tables": false
   },
   "no-duplicate-heading": {
     "siblings_only": true
   },
   "no-inline-html": {
     "allowed_elements": [
-      "span",
+      "br",
       "details",
+      "span",
       "summary"
     ]
   },