From 2fb61f6d6a295b8c261a2b41e1018eaf66e4b5ab Mon Sep 17 00:00:00 2001 From: Alain Krok Date: Mon, 25 Sep 2023 09:29:57 -0700 Subject: [PATCH] chore: initial documentation (#5) * Add templates for bug report, documentation and feature request * add code of conduct, update repo stability, and gitignore for macOS users * add dev and design guidelines, contribution, readme and changelog * update branch name for main --- .github/ISSUE_TEMPLATE/bug_report.yml | 146 ++++++++++++++++++ .github/ISSUE_TEMPLATE/documentation.yml | 23 +++ .github/ISSUE_TEMPLATE/feature_request.yml | 47 ++++++ .gitignore | 1 + .projenrc.ts | 2 + CHANGELOG.md | 6 + CODE_OF_CONDUCT.md | 7 +- CONTRIBUTING.md | 171 ++++++++++++++++++--- DESIGN_GUIDELINES.md | 81 ++++++++++ DEVELOPER_GUIDE.md | 69 +++++++++ README.md | 57 +++++-- package.json | 2 +- 12 files changed, 580 insertions(+), 32 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/documentation.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 CHANGELOG.md create mode 100644 DESIGN_GUIDELINES.md create mode 100644 DEVELOPER_GUIDE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..650ef75e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,146 @@ +--- +name: "🐛 Bug Report" +description: Report a bug +title: "(module name): (short issue description)" +labels: [bug, needs-triage] +assignees: [] +body: + - type: textarea + id: description + attributes: + label: Describe the bug + description: What is the problem? A clear and concise description of the bug. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: | + What did you expect to happen? + validations: + required: true + - type: textarea + id: current + attributes: + label: Current Behavior + description: | + What actually happened? + + Please include full errors, uncaught exceptions, stack traces, and relevant logs. + If service responses are relevant, please include wire logs. + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Reproduction Steps + description: | + Provide a self-contained, concise snippet of code that can be used to reproduce the issue. + For more complex issues provide a repo with the smallest sample that reproduces the bug. + + Avoid including business logic or unrelated code, it makes diagnosis more difficult. + The code sample should be an SSCCE. See http://sscce.org/ for details. In short, please provide a code sample that we can copy/paste, run and reproduce. + validations: + required: true + - type: textarea + id: solution + attributes: + label: Possible Solution + description: | + Suggest a fix/reason for the bug + validations: + required: false + - type: textarea + id: context + attributes: + label: Additional Information/Context + description: | + Anything else that might be relevant for troubleshooting this bug. Providing context helps us come up with a solution that is most useful in the real world. + validations: + required: false + + - type: input + id: cdk-version + attributes: + label: CDK CLI Version + description: Output of `cdk version` + validations: + required: true + + - type: input + id: framework-version + attributes: + label: Framework Version + validations: + required: false + + - type: input + id: node-version + attributes: + label: Node.js Version + validations: + required: true + + - type: input + id: operating-system + attributes: + label: OS + validations: + required: true + + - type: dropdown + id: language + attributes: + label: Language + multiple: true + options: + - Typescript + - Python + - .NET + - Java + - Go + validations: + required: true + + - type: input + id: language-version + attributes: + label: Language Version + description: E.g. TypeScript (3.8.3) | Java (8) | Python (3.7.3) + validations: + required: false + + - type: input + id: region + attributes: + label: Region experiencing the issue + description: For instance, us-east-1 + validations: + required: true + + - type: textarea + id: modified + attributes: + label: Code modification + description: | + Was the solution modified from the version published on this repository? If the answer to the previous question was yes, are the changes available on GitHub? + validations: + required: true + + - type: textarea + id: other + attributes: + label: Other information + description: | + e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. associated pull-request, stackoverflow, slack, etc + validations: + required: false + + - type: checkboxes + attributes: + label: Service quota + description: Have you checked your [service quotas](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html) for the services this sample uses? + options: + - label: I have reviewed the service quotas for this construct + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 00000000..85ea43ec --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,23 @@ +--- +name: "📕 Documentation Issue" +description: Report an issue in the API Reference documentation or Developer Guide +title: "(module name): (short issue description)" +labels: [documentation, needs-triage] +assignees: [] +body: + - type: textarea + id: description + attributes: + label: Describe the issue + description: A clear and concise description of the issue. + validations: + required: true + + - type: textarea + id: links + attributes: + label: Links + description: | + Include links to affected documentation page(s). + validations: + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..39d37d48 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,47 @@ +--- +name: 🚀 Feature Request +description: Suggest an idea for this project +title: "(module name): (short issue description)" +labels: [feature-request, needs-triage] +assignees: [] +body: + - type: textarea + id: description + attributes: + label: Describe the feature + description: A clear and concise description of the feature you are proposing. + validations: + required: true + - type: textarea + id: use-case + attributes: + label: Use Case + description: | + Why do you need this feature? For example: "I'm always frustrated when..." + validations: + required: true + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: | + Suggest how to implement the addition or change. Please include prototype/workaround/sketch/reference implementation. + validations: + required: false + - type: textarea + id: other + attributes: + label: Other Information + description: | + Any alternative solutions or features you considered, a more detailed explanation, stack traces, related issues, links for context, etc. + validations: + required: false + - type: checkboxes + id: ack + attributes: + label: Acknowledgements + options: + - label: I may be able to implement this feature request + required: false + - label: This feature might incur a breaking change + required: false \ No newline at end of file diff --git a/.gitignore b/.gitignore index 37f6dbc8..c8e9a283 100644 --- a/.gitignore +++ b/.gitignore @@ -30,6 +30,7 @@ jspm_packages/ *.tgz .yarn-integrity .cache +*.DS_STORE !/.projenrc.js /test-reports/ junit.xml diff --git a/.projenrc.ts b/.projenrc.ts index edaf4ad5..31e9988d 100644 --- a/.projenrc.ts +++ b/.projenrc.ts @@ -38,5 +38,7 @@ const project = new awscdk.AwsCdkConstructLibrary({ docgen: false, licensed: true, license: 'Apache-2.0', + gitignore: ['*.DS_STORE'], + stability: 'experimental', }); project.synth(); \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..d9b2bc1b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,6 @@ +# CDK Emerging Tech Constructs V0.0.0 (2023-09-21) + +Based on CDK library version 2.96.2 + +*** +© Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 5b627cfa..04cb2ca5 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,4 +1,7 @@ ## Code of Conduct -This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). -For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact +This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). +For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact opensource-codeofconduct@amazon.com with any additional questions or comments. + +*** +© Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c4b6a1c5..57cc15f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,13 +6,11 @@ documentation, we greatly value feedback and contributions from our community. Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution. - ## Reporting Bugs/Feature Requests We welcome you to use the GitHub issue tracker to report bugs or suggest features. -When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already -reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: +When filing an issue, please check [existing open](https://github.com/aws-samples/emerging-tech-cdk-constructs/issues), or [recently closed](https://github.com/aws-samples/emerging-tech-cdk-constructs/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20), issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: * A reproducible test case or series of steps * The version of our code being used @@ -20,29 +18,157 @@ reported the issue. Please try to include as much information as you can. Detail * Anything unusual about your environment or deployment -## Contributing via Pull Requests -Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: +## Contributing via Pull Requests -1. You are working against the latest source on the *main* branch. -2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already. -3. You open an issue to discuss any significant work - we would hate for your time to be wasted. +### Pull Request Checklist -To send us a pull request, please: +* [ ] Testing + - Unit test added (prefer not to modify an existing test, otherwise, it's probably a breaking change) + - Integration test added (if adding a new pattern or making a significant update to an existing pattern) +* [ ] Docs + - __README__: README and/or documentation topic updated + - __Design__: For significant features, design document added to `design` folder +* [ ] Title and Description + - __Change type__: title prefixed with **fix**, **feat** or **chore** and module name in parenthesis, which will appear in changelog + - __Title__: use lower-case and doesn't end with a period + - __Breaking?__: last paragraph: "BREAKING CHANGE: " + - __Issues__: Indicate issues fixed via: "**Fixes #xxx**" or "**Closes #xxx**" -1. Fork the repository. -2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change. -3. Ensure local tests pass. -4. Commit to your fork using clear commit messages. -5. Send us a pull request, answering any default questions in the pull request interface. -6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. +--- -GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and -[creating a pull request](https://help.github.com/articles/creating-a-pull-request/). +Projen is opinionated and mandates that all project configuration be done through the .projenrc.ts file. For instance if you directly change package.json then Projen will detect that during the release phase and will fail the release attempt. Hence, it is a good idea to do projen synth by running the projen command on the constructs/ directory where the .projenrc.ts file is before pushing the code to our repository. + +### Step 1: Open Issue + +If there isn't one already, open an issue describing what you intend to contribute. It's useful to communicate in advance, because sometimes, someone is already working in this space, so maybe it's worth collaborating with them instead of duplicating the efforts. + +### Step 2: Design + +If you are proposing a new Emerging Tech Construct, the best way to do this is create the full README.md document for the Construct in advance (defining all interfaces, the minimal deployment scenario, the architecture diagram, etc.). This will give us all the information we need to provide feedback and the document will live on as documentation (saving you that effort labor). Not all groups of CDK L2 objects is a Solutions Construct - you will want to follow our [design guidelines](./DESIGN_GUIDELINES.md). + +Once the design is finalized, you can re-purpose this PR for the implementation, or open a new PR to that end. + +Good AWS Emerging Tech Constructs have the following characteristics: + 1) Multi-service: The goal of AWS Emerging Tech Constructs is to weave multiple services together in a well-architected way. + 2) Configurable Business Logic: AWS Emerging Tech Constructs should be applicable to all businesses and workloads as much as possible so that they are easily reusable. + 3) Reusable across multiple use-cases: We would rather have a small library of Constructs that are wildly popular with customers rather than a huge library of Constructs that customers find irrelevant. + 4) Well Architected: AWS Solutions Constructs should be secure, reliable, scalable and cost efficient. + +### Step 3: Work your Magic + +Now it's time to work your magic. Here are some guidelines: + +* Coding style (abbreviated): + * In general, follow the style of the code around you + * 2 space indentation + * 120 characters wide + * ATX style headings in markdown (e.g. `## H2 heading`) +* Every change requires a unit test +* If you change APIs, make sure to update the module's README file +* Try to maintain a single feature/bugfix per pull request. It's okay to introduce a little bit of housekeeping + changes along the way, but try to avoid conflating multiple features. Eventually all these are going to go into a + single commit, so you can use that to frame your scope. +* If your change introduces a new construct, take a look at the our + [example construct]() for an explanation of the L3 patterns we use. + Feel free to start your contribution by copy&pasting files from that project, + and then edit and rename them as appropriate - + it might be easier to get started that way. +* To ensure CDKv2 compatibility of all the Emerging Tech Constructs, please ensure the code meets the following guidelines: + * Import statement for `Construct` is standalone, for example, `import { Construct } from '@aws-cdk/core';` instead of `import { Construct, App, Aws } from '@aws-cdk/core';` + * Check to make sure the usage of `Construct` in the code is also standalone, for example, `export class IotToSqs extends Construct` insted of `export class IotToSqs extends cdk.Construct` + * Core classes are imported from `@aws-cdk/core` only, for example, `import { Duration } from "@aws-cdk/core;` instead of `import { Duration } from "@aws-cdk/core/lib/duration";` + * DO NOT USE deprecated APIs, it will not build in CDKv2, for example, using `statistic?` attribute of [@aws-cdk/aws-cloudwatch.Alarm](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudwatch.Alarm.html) Construct Props will fail to build in CDKv2 + +#### Integration Tests + +If you are working on a new feature that is using previously unused CloudFormation resource types, or involves +configuring resource types across services, you need to write integration tests that use these resource types or +features. + +To the extent possible, include a section (like below) in the integration test file that specifies how the successfully +deployed stack can be verified for correctness. Correctness here implies that the resources have been set up correctly. +The steps here are usually AWS CLI commands but they need not be. + +```ts +/* + * Stack verification steps: + * * + * * + */ +``` + +### Step 4: Commit + +Create a commit with the proposed changes: + +* Commit title and message (and PR title and description) must adhere to [conventionalcommits](https://www.conventionalcommits.org). + * The title must begin with `feat(module): title`, `fix(module): title` or `chore(module): title`. + * Title should be lowercase. + * No period at the end of the title. + +* Commit message should describe _motivation_. Think about your code reviewers and what information they need in + order to understand what you did. If it's a big commit (hopefully not), try to provide some good entry points so + it will be easier to follow. +* Commit message should indicate which issues are fixed: `fixes #` or `closes #`. -## Finding contributions to work on -Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start. +* Shout out to collaborators. +* If not obvious (i.e. from unit tests), describe how you verified that your change works. + +* If this commit includes breaking changes, they must be listed at the end in the following format (notice how multiple breaking changes should be formatted): + +``` +BREAKING CHANGE: Description of what broke and how to achieve this behavior now +* **module-name:** Another breaking change +* **module-name:** Yet another breaking change +``` + +### Step 5: Pull Request + +* Push to a GitHub fork +* Submit a Pull Requests on GitHub. +* Please follow the PR checklist written above. We trust our contributors to self-check, and this helps that process! +* Discuss review comments and iterate until you get at least one “Approve”. When iterating, push new commits to the + same branch. Usually all these are going to be squashed when you merge to main. The commit messages should be hints + for you when you finalize your merge commit message. +* Make sure to update the PR title/description if things change. The PR title/description are going to be used as the + commit title/message and will appear in the CHANGELOG, so maintain them all the way throughout the process. +* Make sure your PR builds successfully (we have Github actions setup to automatically build all PRs) + +#### Build steps + +- 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, and then published to the configured artifact repositories (e.g. npm, pypi). + +By default, for every commit to the default (main) branch, a new version is released (trunk-based development). This includes the following steps: + +- Compile, lint and test the code. +- Use JSII to produce library artifacts for all target languages. +- Determine the next minor/patch version based on conventional commits. Major versions must be explicitly bumped to protect consumers against breaking changes. +- A changelog entry is generated based on commit history. +Packages are published to all target package managers. + +> **Warning** +> Projen synthesizes files that are part of your source repository. This means that when you change you projenrc file, and execute projen, other files in your repo may change as a result. +> Make sure to push those modified files as well. Otherwise, the self mutation step of the build will fail. This is to ensure that a pull request branch always represent the final state of the repository + +### Step 6: Merge + +* Once approved and tested, a maintainer will squash-merge to main and will use your PR title/description as the + commit message. + +Projen automatically performs semantic versioning based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). + +For example: + +- fix: bump PATCH version (v0.0.1) +- feat: bump MINOR version (v0.1.0) + +MAJOR version must be explicitly bumped by adding majorVersion: x to .projenrc.ts to protect users from critical changes. + +GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and +[creating a pull request](https://help.github.com/articles/creating-a-pull-request/). ## Code of Conduct This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). @@ -56,4 +182,9 @@ If you discover a potential security issue in this project we ask that you notif ## Licensing -See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. +See the [LICENSE](https://github.com/aws-samples/emerging-tech-cdk-constructs/blob/main/LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. + +We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. + +*** +© Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. \ No newline at end of file diff --git a/DESIGN_GUIDELINES.md b/DESIGN_GUIDELINES.md new file mode 100644 index 00000000..443ec637 --- /dev/null +++ b/DESIGN_GUIDELINES.md @@ -0,0 +1,81 @@ +# Design Guidelines + +# Emerging Tech Constructs Design Guidelines + +One of the Emerging Tech Constructs tenets states: + +> **Constructs are Consistent** - once customers are familiar with the use of Constructs, they can adopt additional constructs easily. Customers familiar with using the CDK can easily adopt Constructs. + +This document defines the ways in which Constructs are consistent. When proposing a Emerging Tech Construct, use this document to drive your design. + +## Overall Guidelines + +**Constructs Can Be Self Contained** + +While passing an existing resource to Construct is essential to the ability to link Constructs together, it should never be required. If your Construct requires the client to create a resource to pass in as an argument to the constructor then you have probably not defined your Construct correctly or what you are designing is not a good fit for the Emerging Tech Constructs library. + +**Use CDK definitions to define a service or resource** + +The construct should not create new classes or interfaces to describe services or resources. Although the new class may seem simpler now, as new capabilities are added to the construct the new class will acquire new properties – the ultimate result would be something equivalent to the CDK definition, but not compatible. The CDK definitions are well thought out and interact predictably with other CDK constructs, use them. If you want a client the ability to specify a few attributes of a ConstructProps without specifying every required value, then make the type of that attribute ConstructProps | any. This pattern exists several places in the Emerging Tech Constructs library. + +Another practice that this rule prohibits is putting specific attributes of sub resources in your Emerging Tech Constructs Props object. For instance - if your VPC needs an Internet Gateway, then the client should send VPC Props that create the Internet Gateway, don't create a property at in your Construct Props object of InternetGateway: true. + +**The client should have the option (but not requirement) to provide any props used within the construct** + +When you supply a CDK defined props object to any CDK constructor within your construct (L1 or L2), your construct should be able to generate all the default values required to create that L1 or L2 construct. Alternatively, the client should be able to override any or all of those default props values to completely customize the construct. + +There are exceptions to this rule. The Lambda Function L2 construct, for instance, cannot specify a default value for the Lambda code – the client must provide this. Also, at times the workings of the construct require specific props values to work. In this situation, those values will override user provided values. In general, the props values sent to a CDK constructor are generated like this: + +``` +let actualProps = overrideProps(defaultProps, userProvidedProps); +actualProps = overrideProps(actualProps, constructRequiredProps) +``` + +Construct required props should be minimized and listed in the README.md file for the Construct. +There is a possibility that the client could specify some props values that are incompatible with default props values. That is the responsibility of the client – if they choose to not use the default implementation then they take responsibility for the configuration they specify. + +**The Minimal Deployable Pattern Definition should be minimal** + +While a client should have great flexibility to fully specify how a Construct is deployed, the minimal deployment should consist of a single new statement. At times things like table schema might require some additional code – but if your minimal deployable solution is more than a couple lines long or requires creating one or more services first then your construct is outside the patterns for the library. + +**Business Logic** + +The Construct don't have to be restricted to deploying infrastructure (eg – implemented Lambda functions). This is because we want to abstract the complexity of the underlying emerging technology area. However, the business logic should be configurable to adapt to different use cases. + +**Favor L2 CDK Constructs over L1** + +L1 CDK constructs are merely thin code wrappers over the raw CloudFormation definitions – they bring little if any additional value to the table. L2 CDK constructs provide additional functionality, security and interoperability. Whenever possible, Emerging Tech Constructs interfaces should speak in terms of L2 CDK constructs. If your definition includes L1 constructs it may not be rejected, but you will be asked to explain the reasons requiring their use.  + +## VPCs + +Clients may choose to deploy their architectures for any number of reasons. VPC capability should be added to constructs when traffic within the construct can be restricted within a VPC. + +## Naming + +The name of a Emerging Tech Construct is composed by concatenating the construct's purpose and the names of the individual services or resources configured by the construct. When it is obvious what resource is being deployed by the service, use just the service name, such as SQS, SNS, DynamoDB, etc. When just the service name is ambiguous, append the specific resource type to the service name, such as SagemakerEndpoint (also do this for a different flavor of an already deployed service, such as DynamoDBStream). If you use a specific library, you can also add it to the name. + +For the construct file name, separate the all lower-case service names by dashes and preface the whole name with “aws-“. For Example: + +     aws-ragsource-apigateway-opensearch +     aws-apigateway-sagemakerendpoint + +For the Typescript class name, use Pascal casing and concatenate the names separated by “To”. For Example: + +     RagApigatewayToOpensearch +     ApigatewayToSagemakerendpoint + +Once again, these rules became clear as we wrote all of the existing constructs and not all of the early constructs comply with these rules. + +# Service Usage in Constructs +It's important for consistency that services are implemented consistently across Emerging Tech Constructs – that clients specify the same properties. This section specifies the require attributes on your Construct Props interface for each service currently in the library, as well as the reasons behind any exceptions. We are unlikely to approve a construct with additional attributes, although we may if the proposed new attribute is appropriate for us to implement across all constructs using that service. + +If you are creating a construct that uses a service for the first time, defining the appropriate interface is a key step and we will work with you. + +This version of the document also lists what Constructs currently violate these standards and whether making the object compliant would be a breaking change. + +Existing Inconsistencies would not be published, that’s for our internal use – only the Required Properties and Attributes on Props would be published as requirements (along with specific notes). + +This section evolves as we add new constructs and use new services. + +*** +© Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. \ No newline at end of file diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md new file mode 100644 index 00000000..f02a5aab --- /dev/null +++ b/DEVELOPER_GUIDE.md @@ -0,0 +1,69 @@ +# Developer Guide + +Emerging Tech Constructs are built in typescript using Projen (http://projen.io/). This is to support all the associated testing, code checking and compilation for Typescript and Python client. At the moment, there is no dedicated development container, thus you need to configure your local development environment following the steps described below. + +### Pre-requisites + +- An AWS account. We recommend to deploy this solution in a new account +- [AWS CLI](https://aws.amazon.com/cli/): configure your credentials + +``` +aws configure --profile [your-profile] +AWS Access Key ID [None]: xxxxxx +AWS Secret Access Key [None]:yyyyyyyyyy +Default region name [None]: us-east-1 +Default output format [None]: json +``` + +- [Node](https://nodejs.org/en) >= v18.12.1 +- [AWS CDK](https://github.com/aws/aws-cdk/releases/tag/v2.96.2) >= 2.96.2 +- [Python](https://www.python.org/downloads/) >=3.9 +- [Projen](https://github.com/projen/projen) >= 0.65.14 +- [PNPM](https://pnpm.io/installation) >= 8.7.4 +- [PDK](https://aws.github.io/aws-pdk/getting_started/index.html) >= 0.21.5 + +You can use the command below to install the dependencies listed above +``` +npm install -g npm aws-cdk pnpm @aws/pdk projen +``` + +## Preparing your Build Environment + +| Action | | +| :--------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Open up the [aws-emerging-tech-constructs repo](https://github.com/aws-samples/emerging-tech-cdk-constructs). | As you are reading this file from the aws-emerging-tech-constructs repo, you are probably already there... | +| Using the Fork button at the upper right, Fork the repo into your github account. | While we can give some advice on what github and git commands to use, we will not attempt to be a git tutorial. Some git/github expertise is assumed. | +| Clone forked repo to your local development environment | If you wish to work off a branch in your repository, create that branch now and clone that branch. You will create a PR back to Main in aws-emerging-tech-constructs eventually, you can do that from fork/main or fork/*branch* | +| `cd emerging-tech-cdk-construct` | This is the home directory of the repo, this is where you will open your text editor, run builds, etc. | +| `code .` | Opens the project in VSCode. You can use the editor of your choice, just adapt this step to your specific use case. | +| `npx projen install` | This command will generate project files (dependencies, ...) from the configuration file, and install them. | + + +## Working on Your Construct + + +| Action | Explanation | +| :-------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| (optional)
`git checkout -b your-branch-name` | If you're working in a different branch than main in your forked repo and haven't changed your local branch, now is a good time to do so. | +| `mkdir src/ ` | Creates a dedicated folder to work on your construct. | +| `cd src/` | Change directory to the folder where you want to change code (this might also be `cd core`). | +| *Do all your code editing* | Open your code editor and and create the construct or perform your edits on an existing construct (or core). The Common folder | +| `npx projen build` | This is the build command for the library. It will build, lint and run the unit and integration tests. If you make any substantive changes to the code, you will almost certainly see some or all of the tests fail. The next section will describe how testing works in AWS Emerging Tech Constructs and how to write, refresh and execute tests. In the meantime, you can at least check if your code transpiles correctly without running the tests by running `npm run build`. If you've edited any modules in /core in addition to a construct, be sure to build /core before building your construct. This command also packages locally the constructs to the /dist folder. | + +## Testing + +Emerging Tech Constructs use 2 flavors of testing, unit testing and integration testing. Unit testing targets specific aspects of a construct or one of the functions in the core library. It examines the results and confirms the correct resources are there. For instance, it may call the deployLambdaFunction() in the core library and then confirm that AWS_NODEJS_CONNECTION_REUSE_ENABLED environment variable was set correctly. The unit tests check that certain aspects of the results are correct. You can learn more about unit testing CDK constructs [here](https://docs.aws.amazon.com/cdk/latest/guide/testing.html) and [here](https://aws.amazon.com/blogs/developer/testing-infrastructure-with-the-aws-cloud-development-kit-cdk/). + +All test files can be found in the /test directory under each construct (or core). You'll find 2 types of files in this directory: + +* \*.test.ts files - these are the unit test files. All the unit tests for a construct are in a single file. +* integ.\*.ts files - these the integration test files. Each integration test gets a separate file. + + +| Action | Explanation | +| :------------------ | :------------------------------------------- | +| `npx projen test` | This will run all tests (unit+integration) | + +--- + +© Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. diff --git a/README.md b/README.md index 7f922047..d83c771d 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,56 @@ -## My Project +# Amazon Emerging Tech CDK Constructs -TODO: Fill this README out! + -Be sure to: +--- -* Change the title in this README -* Edit your repository description on GitHub +![Stability: Experimental](https://img.shields.io/badge/stability-Experimental-important.svg?style=for-the-badge) -## Security +> All classes are under active development and subject to non-backward compatible changes or removal in any +> future version. These are not subject to the [Semantic Versioning](https://semver.org/) model. +> This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package. -See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. +--- + -## License +## Table of contents -This library is licensed under the MIT-0 License. See the LICENSE file. +- [Introduction](#introduction) +- [CDK Versions](#cdk-versions) +- [Contributing](#contributing) +- [Adding new constructs](#design-guidelines-and-development-guide) +- [Sample Use Cases](#sample-use-cases) +- [Roadmap](#roadmap) +# Introduction + +The AWS Emerging Tech Constructs library is an open-source extension of the [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) that provides multi-service, well-architected patterns for quickly defining solutions in code to create predictable and repeatable infrastructure, called [constructs](https://docs.aws.amazon.com/cdk/v2/guide/constructs.html). The goal of AWS Emerging Tech Constructs is to accelerate the experience for developers to build solutions of any size using pattern-based definitions for their architecture, around emerging technologies (Generative AI, IoT, Spatial, Robotics, AI/ML) + +The patterns defined in AWS Emerging Tech Constructs are high level, multi-service abstractions of AWS CDK constructs that have default configurations based on well-architected best practices. The library is organized into logical modules using object-oriented techniques to create each architectural pattern model. + +# CDK Versions + +AWS Emerging Tech Constructs and the AWS CDK are independent teams and have different release schedules. Each release of AWS Emerging Tech Constructs is built against a specific version of the AWS CDK. The [CHANGELOG.md](./CHANGELOG.md) file lists the CDK version associated with each AWS Emerging Tech Constructs release. For instance, AWS Emerging Tech Constructs v0.0.0 was built against AWS CDK v2.96.2. This means that to use AWS Emerging Tech Constructs v0.0.0, your application must include AWS CDK v2.96.2 or later. You can continue to use the latest AWS CDK versions and upgrade the your AWS Emerging Tech Constructs version when new releases become available. + +# Contributing + +Contributions of all kinds are welcome! Check out our [contributor's guide](./CONTRIBUTING.md) + +# Design guidelines and Development guide + +If you want to add a new construct to the library, check out our first our [design guidelines](./DESIGN_GUIDELINES.md), then follow the [development guide](./DEVELOPER_GUIDE.md) + +# Sample Use Cases + +This library includes a collection of functional use case implementations to demonstrate the usage of AWS Emerging Tech Constructs architectural patterns. These can be used in the same way as architectural patterns, and can be conceptualized as an additional "higher-level" abstraction of those patterns. Those patterns (constructs) are composed together into [stacks](https://docs.aws.amazon.com/cdk/latest/guide/stacks.html), forming a "CDK app". + +The following use cases are provided as functional examples: + +Coming soon + +# Roadmap + +Coming soon + +*** +© Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. \ No newline at end of file diff --git a/package.json b/package.json index b373b48d..a911c293 100644 --- a/package.json +++ b/package.json @@ -113,7 +113,7 @@ } }, "types": "lib/index.d.ts", - "stability": "stable", + "stability": "experimental", "jsii": { "outdir": "dist", "targets": {},