feat: document AWS cloud development features (projen#1257)

FitX · Nov 25, 2021 · 1563f29 · 1563f29
1 parent 1759169
commit 1563f29
Show file tree

Hide file tree

Showing 5 changed files with 240 additions and 173 deletions.
diff --git a/VISION.md b/VISION.md
@@ -31,17 +31,17 @@ We will also need to indicate major version compatibility of each project/compon
 
 ### Velocity
 
-In semver (semantic versioning), the only right way to introduce a breaking change (API or behavioral) is to release 
-a new major version. It will take a couple of years for projen to stabilize, and we want the ecosystem to grow with it. 
+In semver (semantic versioning), the only right way to introduce a breaking change (API or behavioral) is to release
+a new major version. It will take a couple of years for projen to stabilize, and we want the ecosystem to grow with it.
 A monolithic module makes this less of a problem because there aren't many libraries that depend on projen, so a major
 version once in a while is tolerable.
 
-This means that projen will release major versions all the time. Think 232.4.34. 
+This means that projen will release major versions all the time. Think 232.4.34.
 
-So we need our ecosystem to continuously take updates and release new versions that were tested with the new major version. 
+So we need our ecosystem to continuously take updates and release new versions that were tested with the new major version.
 In most cases, projects and component won't get broken, but sometimes they will and then the maintainer will need to resolve.
-Luckily this mechanism already exists in projen (`projenUpgradeSecret`). 
-It is opt-in because it requires a the user to upload a GitHub secret, but maybe if we implement some support for secret management, 
+Luckily this mechanism already exists in projen (`projenUpgradeSecret`).
+It is opt-in because it requires a the user to upload a GitHub secret, but maybe if we implement some support for secret management,
 we could make that the default behavior.
 
 As mentioned above, when we process our "sources" during build, we can check the projen version they were tested with and
@@ -62,3 +62,7 @@ inside projen components.
 - [ ] Discoverability of external components/modules through the CLI
 - [ ] Support projenrc in YAML (fully declarative, if one desires)
 - [x] CLI bash completion
+- [ ] License checking (non CDK specific)
+- [ ] Multi-repository projects (alternative to mono-repos)
+- [ ] IDE integration (e.g. task execution)
+- [ ] Support multiple workflow engines (currently only GitHub is supported)
diff --git a/docs/aws-lambda.md b/docs/aws-lambda.md
diff --git a/docs/awscdk-apps.md b/docs/awscdk-apps.md
@@ -0,0 +1,15 @@
+# AWS CDK Applications
+
+Project types: `awscdk-app-java`, `awscdk-app-ts`.
+
+## Deployment (NOT IMPLEMENTED YET)
+
+CDK application projects produce complete cloud applications. When a commit is
+merged into the default branch, the app is rolled out by the release workflow to
+AWS environments.
+
+## Dev Stage (NOT IMPLEMENTED YET)
+
+Every app includes an instance of the application stage which can be deployed to
+a development AWS account. This allows each developer to use their AWS account
+as part of their development environment.
diff --git a/docs/awscdk-construct.md b/docs/awscdk-construct.md
@@ -1,26 +1,22 @@
 # AWS CDK Construct Library
 
-This projen type is used for building AWS CDK constructs using the jsii. The [jsii](https://github.com/aws/jsii) allows 
-you to write code once in Typescript and it will generate the Python, .net, and Java equivalents. Use this if you'd 
-like to build and distribute CDK constructs for others to use.
+AWS CDK library projects produce artifacts with reusable constructs which can be
+consumed by other AWS CDK libraries or apps. Library artifacts are published to
+private or public package managers under a semantic version.
 
-Class heirarchy: `AwsCdkConstructLibrary` -> `ConstructLibrary` -> `JsiiProject` -> `TypeScriptProject` -> `NodeProject` -> `Project`
+By default, for every commit to the default branch, a new version is released
+(trunk-based development). This includes the following steps:
 
-# Table of Contents
+1. Compile, lint and test the code.
+1. Use [JSII](https://github.com/aws/jsii) to produce library artifacts for all
+   target languages.
+1. Determine the next minor/patch version based on [conventional
+   commits](https://www.conventionalcommits.org). Major versions must be
+   explicitly bumped to protect consumers against breaking changes.
+1. A changelog entry is generated based on commit history.
+1. Packages are published to all target package managers.
 
-* [Getting Started](#getting-started)
-  * [Standard Node Module Fields](#standard-node-module-fields)
-  * [Dependencies](#dependencies)
-  * [jsii Publishing](#jsii-publishing)
-* [Workflows](#workflows)
-* [Scripts](#scripts)
-* [Construct Catalog](#construct-catalog)
-* [API Documentation](#api-documentation)
-* [Project structure](#project-structure)
-* [Migrating existing projects](#migrating-existing-projects)
-* [Feedback](#feedback)
-
-# Getting Started
+## Getting Started
 
 Start like all projen projects:
 
@@ -46,7 +42,7 @@ keywords: ['cloudwatch', 'monitoring']
 ```
 
 All are pretty standard setup and nothing CDK-specific at this point. The `keywords` automatically gets 'cdk' so you don't
-need to specify it. 
+need to specify it.
 
 ## Dependencies
 
@@ -60,11 +56,11 @@ cdkDependencies: ['@aws-cdk/aws-ec2'],
 cdkTestDependencies: ['@aws-cdk/assert'],
 ```
 
-`cdkDependencies` will add both dependencies and peerDependencies to your package.json file with a caret semver 
-requirement (e.g. `^1.67.0`). CDK dependencies must be both direct and peer dependencies, 
-see [this issue](https://github.com/aws/aws-cdk/issues/5064). You can set `cdkVersionPinning` to `true` to use a fixed 
-version, but this means that any consumer of your library will have to use this exact CDK version. 
-Likewise, `cdkTestDependencies` will add dependencies to the `devDependencies`. 
+`cdkDependencies` will add both dependencies and peerDependencies to your package.json file with a caret semver
+requirement (e.g. `^1.67.0`). CDK dependencies must be both direct and peer dependencies,
+see [this issue](https://github.com/aws/aws-cdk/issues/5064). You can set `cdkVersionPinning` to `true` to use a fixed
+version, but this means that any consumer of your library will have to use this exact CDK version.
+Likewise, `cdkTestDependencies` will add dependencies to the `devDependencies`.
 
 Additionally, you can add CDK dependencies using the methods:
 
@@ -77,9 +73,9 @@ project.addCdkTestDependencies('aws-cdk/something-else');
 
 ### Depending on other modules
 
-If your library consumes other jsii modules, you should declare them thorugh the `deps` or `peerDeps` options. `deps` should be used if 
-types from the consumed module is _not_ part of the public API of the library (the module is used as an implementation detail), 
-while `peerDeps` _must_ be used if types from the consumed module are exported as part of your library's API. You can read more 
+If your library consumes other jsii modules, you should declare them thorugh the `deps` or `peerDeps` options. `deps` should be used if
+types from the consumed module is _not_ part of the public API of the library (the module is used as an implementation detail),
+while `peerDeps` _must_ be used if types from the consumed module are exported as part of your library's API. You can read more
 [here](https://github.com/aws/jsii/blob/master/docs/configuration.md#dependency-considerations).
 
 ```ts
@@ -88,10 +84,10 @@ deps: [ 'cdk-time-bomb' ]
 
 A [dependabot](https://dependabot.com/) file will be added unless `dependabot` is set to 'false'.
 
-## jsii Publishing
+## Publishing
 
-As this is a [jsii project](./jsii.md), it will cross-compile to other languages.  You can set up 
-any number of jsii target languages. 
+As this is a [jsii project](./jsii.md), it will cross-compile to other languages.  You can set up
+any number of jsii target languages.
 
 ```typescript
   dotnet: {
@@ -122,19 +118,19 @@ For help in getting these secrets for your project, read the [jsii-release](http
 
 If you don't want to publish a particular package, do not include the `dotnet`, `java`, or `python` field.
 
-# Workflows
+## Workflows
 
 Two workflows will be created as Github Actions:
 
 * The Build workflow - controlled by the `buildWorkflow` field. On a 'pull_request' or 'workflow_dispatch' the library
 will be built and checked for anti-tamper (ensure no manual changes to generated files).
 * The Release workflow - controlled by the `releaseWorkflow` field. On a push to `main` (overridden at
- `props.defaultReleaseBranch`) the library is built, anti-tampered, version bumped with a commit, pushed back to git, 
+ `props.defaultReleaseBranch`) the library is built, anti-tampered, version bumped with a commit, pushed back to git,
  and then published to the configured artifact repositories (e.g. npm, pypi).
 
-# Scripts
+## Tasks
 
-There are a number of package scripts that are created for you. Any of them can be overwritten using the `addScript*` 
+There are a number of package scripts that are created for you. Any of them can be overwritten using the `addScript*`
 methods.
 
 script|description
@@ -157,63 +153,43 @@ docgen|generate documentation
 
 As you develop your library you'll likely be using the `test:watch` command the most.
 
-# Construct Catalog
-
-Finally, a field for setting up publishing to the [construct catalog](https://awscdk.io):
-
-```typescript
-  catalog: {
-    announce: true,
-    twitter: '@yourhandle'
-  }
-```
-
-These values are optional but allow the construct catalog's Twitter account to mention your handle on the tweet. Setting `announce`
-to 'false' will stop all tweets about the library. However, the library will still be indexed.
-
-# API Documentation
+## API Documentation
 
 Docs will be generated from [Typescript comments](https://typedoc.org/guides/doccomments/) and saved in the `API.md` file.
-Please review this file regularly and document your constructs liberally. 
+Please review this file regularly and document your constructs liberally.
 
-# Project structure
+## Project structure
 
 ```
 .
-|--lib/ (generated)
+|--lib/ (build output)
 |--src/
    |--main.ts
 |--test/
    |--main.test.ts
 ```
 
-Source .ts files should reside in the `src` directory. Constructs should be exported from the main.ts file. 
-Compiled files will be put in the `lib` directory. Tests are in the `test` directory. If you need additional 
+Source .ts files should reside in the `src` directory. Constructs should be exported from the main.ts file.
+Compiled files will be put in the `lib` directory. Tests are in the `test` directory. If you need additional
 resources that are packaged with your library, add those to a `resources` directory that is besides the `src` directory
 and modify your references accordingly:
 
 ```typescript
 const thing = require('../resources/some-resource.json')
 ```
 
-# Migrating existing projects
+## Migrating existing projects
 
 Your existing CDK constructs likely have a different file structure than what this projen project expects. Projen projects
 are highly opinionated. There are a few expectations of this project you should modify your existing library to conform to:
 
-* All .ts files are expected to be in the `src/` directory. Existing constructs should all be moved there. However, 
+* All .ts files are expected to be in the `src/` directory. Existing constructs should all be moved there. However,
 you can override this directory by setting `srcdir`.
 * Compiled .js and .d.ts files will go into the `lib/` directory. This directory will be removed and rebuilt each build.
 Do not store source .ts files in your `lib/` or 'libdir'.
-* The entrypoint file for all constructs should be `src/main.ts`. If your existing library is not in the main.ts file, 
+* The entrypoint file for all constructs should be `src/main.ts`. If your existing library is not in the main.ts file,
 you can add the following to export it:
 
 ```typescript
 export * from './our-s3-bucket'
 ```
-
-# Feedback
-
-If you find there is anything we missed, please submit Issues or (better yet) Pull Requests on Github.
-
-