Merge pull request #47 from alma-cdk/chore/update-docs

chore: Update docs (Migration Guide) and branding (Logo & Assets)

.github/ISSUE_TEMPLATE/v1-migration-issue.yml

@@ -0,0 +1,54 @@
+name: "V0 to V1 Migration Issue"
+title: "Issue with V1 Migration: "
+description: >
+  Report an issue with the V0 to V1 migration.
+assignees:
+  - maintainers
+
+labels:
+- v1-migration-issue
+
+body:
+
+- type: dropdown
+  attributes:
+    label: Language
+    description: Programming Language used with AWS CDK
+    options:
+      - TypeScript/JavaScript
+      - Python
+      - Go
+  validations:
+    required: true
+
+- type: input
+  attributes:
+    label: Version of aws-cdk-lib
+    description: >
+      AWS CDK Library version used
+  validations:
+    required: true
+
+- type: input
+  attributes:
+    label: Version of aws-cdk
+    description: >
+      AWS CDK CLI/Toolkit version used
+  validations:
+    required: true
+
+- type: input
+  attributes:
+    label: Original version of @alma-cdk/project
+    description: >
+      The v0 version used before migration to v1
+  validations:
+    required: true
+
+- type: textarea
+  attributes:
+    label: Explain the problem
+    description: Do not disclose any sensitive information (including AWS Account IDs)!
+    placeholder: Tell us what happened. Do not disclose any sensitive information (including AWS Account IDs)!
+  validations:
+    required: true

.projenrc.ts

@@ -70,6 +70,8 @@ const project = new awscdk.AwsCdkConstructLibrary({
     "/examples/**/.git",
     "TODO.md",
     ".scannerwork/",
+    "**/*.drawio.bkp",
+    "**/*.afdesign~lock~",
   ],
 });
 

README.md

@@ -1,38 +1,37 @@
 <div align="center">
-	<br/>
-	<br/>
   <h1>
-	<img width="300" src="assets/alma-cdk-project.svg" alt="Alma CDK Project" />
+	<img width="512" src="assets/alma-cdk-project.svg" alt="Alma CDK Project" />
   <br/>
   <br/>
   </h1>
 
-  ![NPM License](https://img.shields.io/npm/l/%40alma-cdk%2Fproject)
+  ![Stability: Stable](https://img.shields.io/badge/stability-stable-%234BCA2A)
+  ![Versioning: SemVer 2.0.0](https://img.shields.io/badge/versioning-semver_2.0.0-blue)
   [![release](https://github.com/alma-cdk/project/actions/workflows/release.yml/badge.svg)](https://github.com/alma-cdk/project/actions/workflows/release.yml)
+  [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=alma-cdk_project&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=alma-cdk_project)
+  [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=alma-cdk_project&metric=coverage)](https://sonarcloud.io/summary/new_code?id=alma-cdk_project)
+  <hr/>
+</div>
 
-  ```sh
-  npm i -D @alma-cdk/project
-  ```
+> [!Tip]
+> Migrating from `v0` to `v1`? See [Migration Guide](/docs/MIGRATION-GUIDE-0-to-1.md).
 
-  <div align="left">
+<br/>
 
-  Opinionated CDK “framework” with constructs & utilities for:
-  - deploying multiple environments to multiple accounts (with many-to-many relationship)
-  - managing account configuration through standardized props (no more random config files)
-  - querying account and/or environment specific information within your CDK code
-  - enabling dynamic & short-lived “feature-environments”
-  - enabling well-defined tagging
-  - providing structure & common conventions to CDK projects
-  - choosing the target account & environment by passing in runtime context:
+Opinionated CDK “framework” with constructs & utilities for:
+- deploying multiple environments to multiple accounts (with many-to-many relationship)
+- managing account configuration through standardized props (no more random config files)
+- querying account and/or environment specific information within your CDK code
+- enabling dynamic & short-lived “feature-environments”
+- enabling well-defined tagging
+- providing structure & common conventions to CDK projects
+- choosing the target account & environment by passing in runtime context:
 
-    ```sh
-    npx cdk deploy -c account=dev -c environment=feature/abc-123
-    ```
-    ... which means you don't need to define all the possibile environments ahead of time!
+  ```sh
+  npx cdk deploy -c account=dev -c environment=feature/abc-123
+  ```
+  ... which means you don't need to define all the possible environments ahead of time!
 
-  </div>
-  <br/>
-</div>
 
 
 ## Account Strategies
@@ -214,20 +213,6 @@ Generally speaking you would be most interested in the following:
 - EnvironmentContext (EC)
 - Name / UrlName / PathName
 
-## Migration
-
-### v0 to v1
+Migrating from `v0` to `v1`? See [Migration Guide](/docs/MIGRATION-GUIDE-0-to-1.md).
 
-#### Tagging behavior
-
-Due to a bug in `v0`, the `Contact` and `Organization` tags were NOT applied as they should have. This means that by default, upgrading from v0→v1 introduces CloudFormation diff. Basically adding the `Contact` and `Organization` tags to all resources. This should be safe operation, but we allow disabling it via a feature flag (note that `Contact` and `Organization` tags will most likely be enforced in future `v2`).
-
-```diff
-// cdk.json
-{
-  "context": {
-    // existing context keys
-+   "@alma-cdk/project:compatibilityV0Tags": true
-  },
-}
-```
+<br/>