diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml new file mode 100644 index 0000000000..ba50a693ae --- /dev/null +++ b/.github/workflows/release-drafter.yml @@ -0,0 +1,32 @@ +name: Release Drafter + +# PROCESS +# +# 1. Enumerate all PRs in merged state +# 2. Filter out any PR labeled `skip-changelog` +# 3. Updates or creates a new release in Draft mode + +# USAGE +# +# Always run on merged PRs or manually via GitHub UI for debugging purposes. +# +# see .github/release-drafter.yml for configuration + +on: + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: read + +jobs: + update_release_draft: + runs-on: ubuntu-latest + permissions: + contents: write # create release in draft mode + steps: + - uses: release-drafter/release-drafter@65c5fb495d1e69aa8c08a3317bc44ff8aabe9772 # v5.20.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 906af7ff70..cedafa950d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,335 +1,159 @@ -# Contributing Guidelines - -Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional -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. - ## Table of contents -- [Security issue notifications](#security-issue-notifications) -- [Code of Conduct](#code-of-conduct) - [Reporting Bugs/Feature Requests](#reporting-bugsfeature-requests) - [Contributing via Pull Requests](#contributing-via-pull-requests) - - [Summary](#summary) - - [Step 1: Find something to work on](#step-1-find-something-to-work-on) - - [Step 2: Design](#step-2-design) - - [Step 3: Work your Magic](#step-3-work-your-magic) - - [Step 4: Pull Request](#step-4-pull-request) - - [Step 5: Merge](#step-5-merge) -- [Setup Development Environment](#setup-development-environment) - - [Prerequisites](#prerequisites) - - [Repo Layout](#repo-layout) - - [Tests](#tests) - - [Unit tests](#unit-tests) - - [Integration tests](#integration-tests) - - [Run e2e tests on your forked project](#run-e2e-tests-on-your-forked-project) - - [Documentation](#documentation) - - [API reference](#api-reference) - - [Docs website](#docs-website) - - [Build \& Package](#build--package) - - [Conventions](#conventions) + - [Dev setup](#dev-setup) + - [Gitpod](#gitpod) + - [GitHub Codespaces](#github-codespaces) + - [Local environment](#local-environment) + - [Sending a pull request](#sending-a-pull-request) + - [Local documentation](#local-documentation) +- [Conventions](#conventions) + - [General terminology and practices](#general-terminology-and-practices) + - [Testing definition](#testing-definition) +- [Finding contributions to work on](#finding-contributions-to-work-on) +- [Code of Conduct](#code-of-conduct) +- [Security issue notifications](#security-issue-notifications) - [Licensing](#licensing) -## Security issue notifications +# Contributing Guidelines -If you discover a potential security issue in this project, we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue. +Thank you for your interest in contributing to our project. Whether it's a [bug report](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2Fbug%2Ctriage&projects=aws-powertools%2F7&template=bug_report.yml&title=Bug%3A+TITLE), [new feature](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2Ffeature-request%2Ctriage&projects=aws-powertools%2F7&template=feature_request.yml&title=Feature+request%3A+TITLE), [correction](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose), or [additional documentation](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=area%2Fdocumentation%2Ctriage&projects=aws-powertools%2F7&template=documentation_improvements.yml&title=Docs%3A+TITLE), we greatly value feedback and contributions from our community. -## 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 opensource-codeofconduct@amazon.com with any additional questions or comments. +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: +We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements. -* A reproducible test case or series of steps -* The version of our code being used -* Any modifications you've made relevant to the bug -* Anything unusual about your environment or deployment +[When filing an issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose), please check [existing open](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc), or [recently closed](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed), issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. ## Contributing via Pull Requests -Contributions via pull requests are much appreciated. - -### Summary - -* This project uses `node@18.x` and `npm@9.x` for development (see [Setup](#setup)). -* Before opening a Pull Request, please find the existing related issue or open a new one to discuss the proposed changes. A PR without a related issue or discussion has a high risk of being rejected. We are very appreciative and thankful for your time and efforts, and we want to make sure they are not wasted. -* After your proposal has been reviewed and accepted by at least one of the project's maintainers, you can submit a pull request. -* When opening a PR, make sure to follow the checklist inside the pull request template. - -### Step 1: Find something to work on - -If you want to contribute a specific feature or fix you have in mind, look at active [pull -requests](https://github.com/aws-powertools/powertools-lambda-typescript/pulls) to see if someone else is already working on it. If not, you can start designing your changes. - -On the other hand, if you are here looking for an issue to work on, check out our [backlog of -issues](https://github.com/aws-powertools/powertools-lambda-typescript/issues) and find something that piques your interest. Our project, by default, uses the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any issue labeled as 'help wanted' or 'good-first-issue' is a great place to start. - -It's a good idea to keep the priority of issues in mind when deciding what to -work on. If we have labelled an issue as `priority:medium` or `priority:low`, it means it's something we won't -get to soon while `priority:high` issues have a bigger impact, so we are much more likely to give a PR for those issues prompt attention. - -### Step 2: Design - -You can start by checking the project's tenets [here](https://docs.powertools.aws.dev/lambda-typescript/latest/#tenets). - -We ask you to seek feedback and consensus on your proposed change by iterating on a design document. This is especially useful when you plan a big change or feature, or you want advice on what would be the best path forward. - -If you're picking up an existing issue, you can simply post your comment and discuss your proposed changes. If instead you're proposing a new feature, you can start by creating a new [RFC issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=RFC%2C+triage&template=rfc.md&title=RFC%3A+) and discuss your proposed change with the maintainers. - -This is a great way to get feedback on your proposed change and make sure that it is in line with the project's direction and community needs. You can start working on the change when you've gotten approved by at least one maintainer - we would hate for your time to be wasted. - -### Step 3: Work your Magic - -Work your magic. Before starting, make sure to check the [Getting Started](#Getting-Started) section to setup your dev environment and familiarize yourself with the project's structure and design. Here are some additional guidelines: - -* Working against the latest source on the **main** branch. -* 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. -* Try to add [unit tests](#Tests) that test your changes when applicable. This is especially important for new features and bug fixes, as it helps you to make sure that your changes are working as intended. -* Lint and test the code. When you've setup the repository with `npm run init-environment`, pre-commit and push-hooks will automatically lint and test the code. Pull request builds will run the same checks as well. - -### Step 4: Pull Request - -Once you're done with your changes, you can open a pull request. Make sure to follow the checklist inside the pull request template: - -* Create a commit with your changes and push them to a - [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo). - > Note: Core members can push directly to a branch on the Powertools for AWS Lambda (TypeScript) repo (following the same conventions detailed below). -* Create a [pull request on GitHub](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). - -Pull request title and message (and PR title and description) must adhere to [conventionalcommits](https://www.conventionalcommits.org), this is enforced by the CI. This is a summary of the rules: -* The title must begin with `feat(module): title`, `fix(module): title`, `refactor(module): title` or `chore(module): title`, etc. -* Title should be lowercase. -* No period at the end of the title. - -The pull request body should describe _motivation_ and follow the template provided as closely as possible. 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. - -The body should also include a reference to the issue or RFC that this PR is related to in the appropriate section. - -Once the pull request is submitted, a reviewer will be assigned by the maintainers. - -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 the maintainers merge to `main`. The commit messages should be hints for you when you finalize your merge commit message. - -> **Note** -> Please do not remove the legal notice at the end of the PR message. This is a requirement for any pull request to be reviewed & accepted into the project. - -### Step 5: Merge - -Once approved and tested, one of the maintainers will squash-merge to `main` and will use your PR title/description will be used as the commit message. Your name will be also added to the Release Notes of the next release. - -## Setup Development Environment - -The following sections describe how to set up the Powertools for AWS Lambda (TypeScript) repository on your local machine and perform common development tasks. - -The alternative is to use a Cloud IDE like [Gitpod](https://www.gitpod.io/) or [GitHub CodeSpaces](https://github.com/features/codespaces) for your development. To quickly get up and running you can click one of these button to open a cloned version of this repo with all of the prerequisites and dependencies installed: +Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/aws-powertools/powertools-lambda-typescript) -[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=305501331) +1. You are working against the latest source on the **main** branch, unless instructed otherwise. +2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already. +3. You discuss and agree your proposed changes under [an existing issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aopen+is%3Aupdated-desc) or a [new issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose){target="_blank" rel="nofollow"} before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful. -### Prerequisites +At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated. -#### Required - -- [Node.js 18.x](https://nodejs.org/download/release/latest-v18.x/) - - If you use [nvm](https://github.com/nvm-sh/nvm#nvmrc) or [fnm](https://github.com/Schniz/fnm) you can install the version used in the project with `nvm use` or `fnm use` respectively. Both will use the `.nvmrc` file in the project's root. -- [npm 9.x](https://www.npmjs.com/) - - After installing the Node.js version above, your npm version should be already 9.x as it comes bundled with Node.js. - -#### Optional - -- [AWS SAM CLI >= 1.65.0](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) - - AWS SAM CLI is a command line interface for AWS Serverless Application Model (SAM), it's used in one of the examples, and it's part of the pre-push hook. -- [Docker](https://docs.docker.com/get-docker/) - - Docker is used to build documentation and Layer. - -First, [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository, and then run the following commands to clone and initialize the repository locally. - -> **Note** -> In order for the commands below to work you need Node.js `18.x` and npm `9.x` - -```console -git clone https://github.com/{your-account}/powertools-lambda-typescript.git -cd aws-lambda-powertools-typescript -npm run setup-local -``` - -We recommend that you use [Visual Studio Code](https://code.visualstudio.com/) to work on the repo. We use `eslint` and `prettier` to keep our code consistent in terms of style and reducing defects, installing [eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extensions will help you to keep the code consistent by highlighting any issues in your code and automatically fixing them. - -### Repo Layout - -The Powertools for AWS Lambda (TypeScript) is fully written in [TypeScript](https://www.typescriptlang.org/) and uses a monorepo structure [managed using npm workspaces](https://docs.npmjs.com/cli/v8/using-npm/workspaces). -If you're unfamiliar with any of these topics, it is useful to learn about them and will make understanding the codebase easier but strictly not necessary for simple contributions. - -The repo contains `packages/` directory that contains the Powertools for AWS Lambda (TypeScript) utilities modules. For instance, the source code for the Logger utility can be found at the location `packages/logger` and so on. -The repo also contains a `packages/commons` directory that holds code and logic shared between one or more utilities and that is published as a separate npm package. - -There are also other workspaces that are not part of the Powertools for AWS Lambda (TypeScript) utilities modules, but are used for examples (`examples/*`), documentation (`docs/snippets`), and Lambda Layers (`layers`). - -### Tests - -Unit and integration (e2e) tests can be found under the `tests` folder of each module. - -You can run each group separately or all together thanks to [jest-runner-groups](https://www.npmjs.com/package/jest-runner-groups). - -Unit tests, under `tests/unit` folder, are standard [Jest](https://jestjs.io) unit tests that aim to test the module features in isolation. - -Integration tests, under `tests/e2e` folder, will test the module features by deploying AWS Lambda functions into your AWS Account. We use [AWS CDK](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) for creating the infrastructure, and the AWS SDK for invoking the functions. - -#### Unit tests - -##### Write - -As mentioned before, tests are split into groups thanks to [jest-runner-groups](https://www.npmjs.com/package/jest-runner-groups), and therefore, each test needs to be tagged properly by adding the following comments in the header of your unit test file: - -```typescript -/** - * Tests metrics - * - * @group unit// - */ -``` - -##### Run - -To run unit tests, you can either use: - -* `npm test -ws` while in the root folder to run them all -* `npm test -w packages/metrics` while in the root folder to run all the unit tests that belong to an utility - -#### Integration tests - -> **Note** -> Running teh end-to-end tests will deploy AWS resources in your AWS account, which might incur costs. The cost from **some services** are covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but not all of them. If you don't have an AWS Account, follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/). Alternatively, you can we will run the tests for you in CI when you submit a pull request. - -##### Set up - -As mentioned, the integration tests use AWS CDK to create the infrastructure needed for the tests. If this is the first time you use CDK, you need to run [`cdk bootstrap`](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) in the account and region you are going to run e2e tests in. - -##### Write - -Similar to unit tests, e2e tests are split into groups thanks to [jest-runner-groups](https://www.npmjs.com/package/jest-runner-groups), and therefore, each test needs to be tagged properly by adding the following comments in the header of your unit test file: - -```typescript -/** - * Tests data lake catalog - * - * @group e2e// - */ +```mermaid +timeline + title Code integration journey (CI) + Project setup
(make dev) : Code checkout + : Dependencies + : Git pre-commit hooks + : Local branch + : Local changes + : Local tests + + Pre-commit checks
(git commit) : Code linting (standards) + + Pre-Pull Request
(git push) : Tests (unit) + + Pull Request
(CI checks) : Semantic PR title check + : Related issue check + : Acknowledgment check + : Code coverage diff + : Contribution size check + : Contribution category check + : GitHub Actions security check + : Quality checks (SonarCloud) + : End-to-end tests (manual by maintainer) + : +pre-commit & pre-pull request checks + + After merge
(CI checks) : GitHub Actions security check + : Rebuild Changelog + : Deploy staging docs + : Update draft release ``` -Follow this convention for the test filename: `..test.ts`. (e.g. `sampleRate.decorator.test.ts`, `childLogger.manual.test.ts`) +### Dev setup -See `metrics/tests/e2e/basicFeatures.decorator.test.ts` as an example. +Firstly, [fork the repository](https://github.com/aws-powertools/powertools-lambda-typescript/fork). -##### Run +To setup your development environment, we recommend using our pre-configured Cloud environment like Gitpod or GitHub Codespaces. -To run e2e tests, you can either use: +#### Gitpod -* `npm test:e2e -ws` while in the root folder to run them all -* `npm test:e2e -w packages/metrics` while in the root folder to run the module specific ones +To start using Gitpod, copy the following URL and replace `YOUR_USERNAME` with your GitHub username or organization: -Four important environment variables can be used: - -* `RUNTIME` to select the runtime to use for the Lambda functions (default: `nodejs18x`) -* `AWS_PROFILE` to use the right AWS credentials -* `AWS_REGION` to select the region to deploy e2e tests infrastructure to -* `DISABLE_TEARDOWN` if you don't want your stack to be destroyed at the end of the test (useful in dev mode when iterating over your code). - -Example: `DISABLE_TEARDOWN=true RUNTIME=nodejs18 AWS_PROFILE=dev-account AWS_REGION=eu-west-1 npm test:e2e -w packages/metrics` - -Below is a diagram that shows the flow of the integration tests: - -```mermaid -sequenceDiagram - Dev Environment / CI->>+Jest: npm run test:e2e - Jest-->Jest: Synthetize CloudFormation Stack - Jest->>+AWS: Deploy Stack - Jest->>+AWS: Invoke Lambda function - AWS->>Jest: Report logs / results - Jest-->Jest: Assert logs/result - Jest->>+AWS: Destroy Stack - Jest->>+Dev Environment / CI: show test results +```text +https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-typescript ``` -##### Run e2e tests on your forked project +This will allow the Cloud environment to target your fork correctly. -You can run the end-to-end tests automatically on your forked project by following these steps: +#### GitHub Codespaces -1. Create an IAM role in your target AWS account, with the least amount of privilege. +To start using GitHub Codespaces, navigate to your fork of the repository, then click on the green `Code` button, and select `Create codespace on ` under the `Codespaces` tab (where `` is the branch you want to work on). - As mentioned above in this page, we are leveraging CDK to deploy and consequently clean-up resources on AWS. Therefore, to run those tests through GitHub actions, you will need to grant specific permissions to your workflow. +#### Local environment - We recommend following [Amazon IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) for the AWS credentials used in GitHub Actions workflows, including: - * Do not store credentials in your repository's code. - * [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) to the credentials used in GitHub Actions workflows. Grant only the permissions required to perform the actions in your GitHub Actions workflows. - * [Monitor the activity](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#keep-a-log) of the credentials used in GitHub Actions workflows. +Alternatively, you can use `npm run setup-local` on your local machine. - For an example of how to create a role in CDK, you can look at [@pahud/cdk-github-oidc](https://constructs.dev/packages/@pahud/cdk-github-oidc) construct. +### Sending a pull request - More information about: +To send us a pull request, please follow these steps: - * [GitHub OpenID Connect](https://github.blog/changelog/2021-10-27-github-actions-secure-cloud-deployments-with-openid-connect/) - * ["Configure AWS Credentials" Action For GitHub Actions](https://github.com/aws-actions/configure-aws-credentials/) +1. Create a new branch to focus on the specific change you are contributing e.g. `improv/logger-debug-sampling` +2. Make sure that all formatting, linting, and tests tasks run as git pre-commit & pre-push hooks are passing. +3. Commit to your fork using clear commit messages. +4. Send us a pull request with a [conventional semantic title](https://github.com/aws-powertools/powertools-lambda-typescript/pull/1744), and answer any default question in the pull request interface. +5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. -2. Add your new role into your [GitHub fork secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) with name `AWS_ROLE_ARN_TO_ASSUME`. -3. In your forked repository, go to the "Actions" tab and select the `run-e2e-tests` workflow. -4. On the `run-e2e-tests` workflow page, select "Run workflow" and run it on the desired branch. +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/). -> :warning: **Don't automatically run end-to-end tests on branch push or PRs**. A malicious attacker can submit a pull request to attack your AWS account. Ideally, use a blank account without any important workload/data, and limit `AWS_ROLE_ARN_TO_ASSUME` permission to least minimum privilege. +### Local documentation -### Documentation +You might find useful to run both the documentation website and the API reference locally while contributing: -You might find useful to run both the documentation website and the API reference locally while contributing. +- **Docs website**: `npm run docs-runLocalDocker` + * If this is your first time running the docs, you need to build the image: `npm run docs-buildDockerImage` +- **API reference**: `npm run docs-api-build-run` -#### API reference +## Conventions -You can build and start the API reference website by running these two commands in the project's root: +### General terminology and practices -* `npm run docs-generateApiDoc` OR `typedoc .` -* `npm run docs-runLocalApiDoc` OR `npx live-server api` +| Category | Convention | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Docstring** | We use [TypeDoc](https://typedoc.org) annotations to help generate more readable API references. For public APIs, we always include at least one **Example** to ease everyone's experience when using an IDE. | +| **Style guide** | We use [Eslint](https://eslint.org) and [Prettier](https://prettier.io) to enforce beyond good practices. We use TypeScript types, function return types, and access modifiers to convey intent. | +| **Core utilities** | Core utilities always accept `serviceName` as a constructor parameter, can work in isolation, and are also available in other languages implementation. | +| **Utilities** | Utilities are not as strict as core and focus on community needs: development productivity, industry leading practices, etc. Both core and general utilities follow our [Tenets](https://docs.powertools.aws.dev/lambda/typescript/#tenets). | +| **Errors** | Specific errors thrown by Powertools live within utilities themselves and use `Error` suffix e.g. `IdempotencyKeyError`. | +| **Git commits** | We follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly. | +| **API documentation** | API reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise. | +| **Documentation** | We treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features. | -#### Docs website +### Testing definition -You can build and start a local docs website by running: +We group tests in different categories -`npm run docs-website-build-run` +| Test | When to write | Notes | Speed | +| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | +| Unit tests | Verify the smallest possible unit works. | Networking access is prohibited. Keep mocks and spies at minimum. | Fast (ms to few seconds at worst) | +| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. Also referred to as integration tests. | It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc. | Slow (minutes) | +| Performance tests | Ensure critical operations won't increase latency and costs to customers. | CI arbitrary hardware can make it flaky. We'll resume writing perf test after we revamp our unit/functional tests with internal utilities. | Fast to moderate (a few seconds to a few minutes) | -Alternatively you can run these two commands: +**NOTE**: Unit tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required. -* `npm run docs-buildDockerImage` OR `docker build -t squidfunk/mkdocs-material ./docs/` -* `npm run docs-runLocalDocker` OR `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material` +## Finding contributions to work on -### Build & Package +Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use GitHub issue labels, [looking at any 'help-wanted' issues is a great place to start](https://github.com/orgs/aws-powertools/projects/7/views/3?query=is%3Aopen+sort%3Aupdated-desc). -In some cases, you might want to build and package the utilities to test them in a separate project or to make sure that the bundling is working as expected. - -Before running the following commands, make sure that you have installed the dependencies for the current branch by running `npm ci` in the root folder: -- `npm run build` to build the project, this will generate a `lib` folder in each one of the packages folders. -- `npm pack -w packages/metrics` to package a specific utility, this will generate a `.tgz` file in the root folder. -- `git restore .` to restore the changes made by the build and package commands. - -If you want to package more than one utility, you can append one or more flags to the same command, for example: `npm pack -w packages/metrics -w packages/logger`. +## Code of Conduct -You can then install the package in your project by running `npm install `. +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 + with any additional questions or comments. -### Conventions +## Security issue notifications -| Category | Convention | -| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Docstring** | We use [TypeDoc](https://typedoc.org) annotations to provide type information and create API references. | -| **Style guide** | We use `eslint` & `prettier` to keep our code consistent in terms of style and reducing defects. | -| **Test coverage** | We use [Jest](https://jestjs.io/) to test our code and [Codecov](https://codecov.io/) to report test coverage. We aim to have 100% test coverage in our unit tests. | -| **Git commits** | We follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). These are not enforced as we squash and merge PRs, but PR titles are enforced during CI. | -| **Documentation** | API reference docs are generated from docstrings which should have an Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strives to be concise. | +If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. ## Licensing diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 7e684dad07..e9e6d1e941 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,302 +1,2 @@ -## Table of contents - -- [Overview](#overview) -- [Current Maintainers](#current-maintainers) -- [Emeritus](#emeritus) -- [Labels](#labels) -- [Maintainer Responsibilities](#maintainer-responsibilities) - - [Uphold Code of Conduct](#uphold-code-of-conduct) - - [Prioritize Security](#prioritize-security) - - [Review Pull Requests](#review-pull-requests) - - [Merging Pull Requests](#merging-pull-requests) - - [Triage New Issues](#triage-new-issues) - - [Triage Bug Reports](#triage-bug-reports) - - [Triage RFCs](#triage-rfcs) - - [Run end to end tests](#run-end-to-end-tests) - - [Releasing a new version](#releasing-a-new-version) - - [Drafting release notes](#drafting-release-notes) - - [Releasing a documentation hotfix](#releasing-a-documentation-hotfix) - - [Maintain Overall Health of the Repo](#maintain-overall-health-of-the-repo) - - [Manage Roadmap](#manage-roadmap) - - [Add Continuous Integration Checks](#add-continuous-integration-checks) - - [Negative Impact on the Project](#negative-impact-on-the-project) - - [Becoming a maintainer](#becoming-a-maintainer) -- [Common scenarios](#common-scenarios) - - [Contribution is stuck](#contribution-is-stuck) - - [Insufficient feedback or information](#insufficient-feedback-or-information) - - [Crediting contributions](#crediting-contributions) - - [Is that a bug?](#is-that-a-bug) - - [Mentoring contributions](#mentoring-contributions) - - [Long running issues or PRs](#long-running-issues-or-prs) -- [Automation](#automation) - -## Overview - -> **Please treat this content as a living document.** - -This is document explains who the maintainers are (see below), what they do in this repo, and how they should be doing it. If you're interested in contributing, see [CONTRIBUTING](CONTRIBUTING.md). - -## Current Maintainers - -| Maintainer | GitHub ID | Affiliation | -| ------------------ | ------------------------------------------- | ----------- | -| Andrea Amorosi | [dreamorosi](https://github.com/dreamorosi) | Amazon | -| Alexander Schueren | [am29d](https://github.com/am29d) | Amazon | - -## Emeritus - -Previous active maintainers who contributed to this project. - -| Maintainer | GitHub ID | Affiliation | -| -------------------------- | --------------------------------------------- | ----------- | -| Sara Gerion | [saragerion](https://github.com/saragerion) | Amazon | -| Florian Chazal | [flochaz](https://github.com/flochaz) | Amazon | -| Chadchapol Vittavutkarnvej | [ijemmy](https://github.com/ijemmy) | Booking.com | -| Alan Churley | [alan-churley](alan-churley) | CloudCall | -| Bahr Michael | [bahrmichael](https://github.com/bahrmichael) | Stedi | - -## Labels - -These are the most common labels used by maintainers to triage issues, pull requests (PR), and for project management: - -| Label | Usage | Notes | -| -------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- | -| triage | New issues that require maintainers review | Issue template | -| area/documentation | Improvements or additions to documentation | Examples/Readme files; Doc additions, fixes, etc.; | -| area/logger | Items related to the Logger Utility | PR automation | -| area/metrics | Items related to the Metrics Utility | PR automation | -| area/tracer | Items related to the Tracer Utility | PR automation | -| area/idempotency | Items related to the Idempotency Utility | PR automation | -| area/parameters | Items related to the Parameters Utility | PR automation | -| area/commons | Items related to the Commons Utility | PR automation | -| area/jmespath | Items related to the JMESPath Utility | PR automation | -| area/validation | Items related to the Validation Utility | PR automation | -| area/batch | Items related to the Batch Processing Utility | PR automation | -| area/parser | Items related to the Parser Utility | PR automation | -| area/automation | Items related to automation like GitHub workflows or CI/CD | PR automation | -| area/layers | Items related to the Lambda Layers pipeline | PR automation | -| size/XS | PRs between 0-9 LOC | PR automation | -| size/S | PRs between 10-29 LOC | PR automation | -| size/M | PRs between 30-99 LOC | PR automation | -| size/L | PRs between 100-499 LOC | PR automation | -| size/XL | PRs between 500-999 LOC, often PRs that grown with feedback | PR automation | -| size/XXL | PRs with 1K+ LOC, largely documentation related | PR automation | -| customer-reference | Authorization to use company name in our documentation | Public Relations | -| community-content | Suggested content to feature in our documentation | Public Relations | -| do-not-merge | PRs that are blocked for varying reasons | Timeline is uncertain | -| type/bug | Unexpected, reproducible and unintended software behavior | PR/Release automation; Doc snippets are excluded; | -| type/bug-upstream | Bug caused by upstream dependency | | -| type/not-a-bug | New and existing bug reports incorrectly submitted as bug | Analytics | -| type/deprecation | This item contains code deprecation | | -| type/duplicate | This issue is a duplicate of an existing one | Analytics | -| type/feature-request | Issue requesting new or enhancements to existing features | Issue template | -| type/feature | PRs that introduce new features | PR automation | -| type/enhancement | PRs that introduce minor changes, usually to existing features | PR automation | -| type/RFC | Technical design documents related to a feature request | | -| type/internal | PRs that introduce changes in governance, tech debt and chores (linting setup, baseline, etc.) | PR automation | -| type/tests | PRs that add or change tests | PR automation | -| type/dependencies | Changes that touch dependencies, e.g. Dependabot, etc. | Issues/PR automation | -| type/breaking-change | Changes that will cause customer impact and need careful triage | | -| status/blocked | Items which progress is blocked by external dependency or reason | | -| status/confirmed | Items with clear scope and that are ready for implementation | | -| status/discussing | Items that need to be discussed, elaborated, or refined | | -| status/on-hold | Items that are on hold and will be revisited in the future | | -| status/pending-release | Merged changes that will be available soon | Release automation auto-closes/notifies it | -| status/completed | Items that are complete and have been merged and/or shipped | | -| status/rejected | This is something we will not be working on. At least, not in the measurable future | | -| status/pending-close-response-required | This issue will be closed soon unless the discussion moves forward | Stale Automation | -| good-first-issue | Something that is suitable for those who want to start contributing | | -| help-wanted | Tasks you want help from anyone to move forward | Bandwidth, complex topics, etc. | -| need-customer-feedback | Tasks that need more feedback before proceeding | 80/20% rule, uncertain, etc. | -| need-more-information | Missing information before making any calls | Signal that investigation or answers are needed | -| need-response | Requires a response from a customer and might be automatically closed if none is received | Marked as stale after 2 weeks, and closed after 3 | -| need-issue | PR is missing a related issue for tracking change | | - -## Maintainer Responsibilities - -Maintainers are active and visible members of the community, and have [maintain-level permissions on a repository](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization). Use those privileges to serve the community and evolve code as follows. - -Be aware of recurring ambiguous situations and [document them](#common-scenarios) to help your fellow maintainers. - -### Uphold Code of Conduct - -Model the behavior set forward by the [Code of Conduct](CODE_OF_CONDUCT.md) and raise any violations to other maintainers and admins. There could be unusual circumstances where inappropriate behavior does not immediately fall within the [Code of Conduct](CODE_OF_CONDUCT.md). - -These might be nuanced and should be handled with extra care - when in doubt, do not engage and reach out to other maintainers and admins. - -### Prioritize Security - -Security is your number one priority. Maintainer's Github keys must be password protected securely and any reported security vulnerabilities are addressed before features or bugs. - -Note that this repository is monitored and supported 24/7 by Amazon Security, see [Reporting a Vulnerability](SECURITY.md) for details. - -### Review Pull Requests - -Review pull requests regularly, comment, suggest, reject, merge and close. Accept only high quality pull-requests. Provide code reviews and guidance on incoming pull requests. - -PRs are [labeled](#labels) based on file changes and semantic title. Pay attention to whether labels reflect the current state of the PR and correct accordingly. - -Use and enforce [semantic versioning](https://semver.org/) pull request titles, as these will be used for [CHANGELOG](CHANGELOG.md) and [Release notes](https://github.com/aws-powertools/powertools-lambda-typescript/releases) - make sure they communicate their intent at the human level. - -For issues linked to a PR, our automation should apply the `status/pending-release` label. Make sure the label is always applied when merging. [Upon release](#releasing-a-new-version), these issues will be notified which release version contains their change. - -See [Common scenarios](#common-scenarios) section for additional guidance. - -### Merging Pull Requests - -Before merging a PR make sure that the title reflects the changes being introduced. - -This project uses the [squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits) strategy which means commits are squashed into a single commit. Instead of seeing all of a contributor's individual commits from a topic branch, the commits are combined into one commit and merged into the default branch. - -This allows you to have control over the commit message although it should match the PR title most of the time. Use and enforce [semantic versioning](https://semver.org/), as these will be used for versioning the next release. - -### Triage New Issues - -Manage [labels](#labels), review issues regularly, and create new labels as needed by the project. Remove `triage` label when you're able to confirm the validity of a request, a bug can be reproduced, etc. Give priority to the original author for implementation, unless it is a sensitive task that is best handled by maintainers. - -Make sure issues are assigned to our [board of activities](https://github.com/orgs/aws-powertools/projects/7) and have the right [status](https://docs.powertools.aws.dev/lambda-typescript/latest/roadmap/#roadmap-status-definition). - -Use our [labels](#labels) to signal good first issues to new community members, and to set expectation that this might need additional feedback from the author, other customers, experienced community members and/or maintainers. - -Be aware of [casual contributors](https://opensource.com/article/17/10/managing-casual-contributors) and recurring contributors. Provide the experience and attention you wish you had if you were starting in open source. - -See [Common scenarios](#common-scenarios) section for additional guidance. - -### Triage Bug Reports - -Be familiar with [our definition of bug](#is-that-a-bug). If it's not a bug, you can close it or adjust its title and labels - always communicate the reason accordingly. - -For bugs caused by upstream dependencies, replace `type/bug` with `type/bug-upstream` label. Ask the author whether they'd like to raise the issue upstream or if they prefer us to do so. - -Assess the impact and make the call on whether we need an emergency release. Contact other [maintainers](#current-maintainers) when in doubt. - -See [Common scenarios](#common-scenarios) section for additional guidance. - -### Triage RFCs - -RFC is a collaborative process to help us get to the most optimal solution given the context. Their purpose is to ensure everyone understands what this context is, their trade-offs, and alternative solutions that were part of the research before implementation begins. - -Make sure you ask these questions in mind when reviewing: - -- Does it use our [RFC template](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=RFC%2Ctriage&template=rfc.yml&title=RFC%3A+TITLE)? -- Does the match our [Tenets](https://docs.powertools.aws.dev/lambda-typescript/latest/#tenets)? -- Does the proposal address the use case? If so, is the recommended usage explicit? -- Does it focus on the mechanics to solve the use case over fine-grained implementation details? -- Can anyone familiar with the code base implement it? -- If approved, are they interested in contributing? Do they need any guidance? -- Does this significantly increase the overall project maintenance? Do we have the skills to maintain it? -- If we can't take this use case, are there alternative projects we could recommend? Or does it call for a new project altogether? - -When necessary, be upfront that the time to review, approve, and implement a RFC can vary - see [Contribution is stuck](#contribution-is-stuck). Some RFCs may be further updated after implementation, as certain areas become clearer. - -An example of a successful RFC: [#447](https://github.com/aws-powertools/powertools-lambda-typescript/issues/447) - -### Run end to end tests - -E2E tests should be ran before every merge to `main` or manually via [run-e2e-tests workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/run-e2e-tests.yml) before making a release. - -To run locally, you need [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites) and an [account bootstrapped](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) (`cdk bootstrap`). With a default AWS CLI profile configured, or `AWS_PROFILE` environment variable set, run `npm run test:e2e -ws`. For more information on how the tests are structured, see [Integration Tests](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/CONTRIBUTING.md#integration-tests). - -### Releasing a new version - -🚧 WIP 🚧 - -#### Drafting release notes - -Visit the [Releases page](https://github.com/aws-powertools/powertools-lambda-typescript/releases) and choose the edit pencil button. - -Make sure the `tag` field reflects the new version you're releasing, the target branch field is set to `main`, and `release title` matches your tag e.g., `v1.4.1`. - -You'll notice we group all changes based on their [labels](#labels) like `type/feature`, `type/bug`, `type/documentation`, etc. - -**All looking good, what's next?** - -The best part comes now. Replace the placeholder `[Human readable summary of changes]` with what you'd like to communicate to customers what this release is all about. Rule of thumb: always put yourself in the customers shoes. - -These are some questions to keep in mind when drafting your first or future release notes: - -- Can customers understand at a high level what changed in this release? -- Is there a link to the documentation where they can read more about each main change? -- Are there any graphics or [code snippets](carbon.now.sh/) that can enhance readability? -- Are we calling out any key contributor(s) to this release? - - All contributors are automatically credited, use this as an exceptional case to feature them - -Once you're happy, hit `Publish release` πŸŽ‰πŸŽ‰πŸŽ‰. - -This will kick off the [Publish docs on release](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/.github/workflows/publish-docs-on-release.yml) workflow that will will notify all the issues labeled as `status/pending-release` of the new release. - -### Releasing a documentation hotfix - -You can rebuild the latest documentation without a full release via this [GitHub Actions Workflow](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/.github/workflows/rebuild-latest-docs.yml). - -Choose `Run workflow`, keep `main` as the branch, and input the latest Powertools for AWS Lambda (TypeScript) version available i.e. `v1.4.1`. - -This workflow will update both user guide and API documentation. - -### Maintain Overall Health of the Repo - -Keep the `main` branch at production quality at all times. If a PR introduces code changes you should make sure that linting and tests are passing before merging. - -### Manage Roadmap - -See [Roadmap section](https://docs.powertools.aws.dev/lambda-typescript/latest/roadmap/) - -Ensure the repo highlights features that should be elevated to the project roadmap. Be clear about the feature’s status, priority, target version, and whether or not it should be elevated to the roadmap. - -### Add Continuous Integration Checks - -Add integration checks that validate pull requests and pushes to ease the burden on Pull Request reviewers. Continuously revisit areas of improvement to reduce operational burden in all parties involved. - -### Negative Impact on the Project - -Actions that negatively impact the project will be handled by the admins, in coordination with other maintainers, in balance with the urgency of the issue. Examples would be [Code of Conduct](CODE_OF_CONDUCT.md) violations, deliberate harmful or malicious actions, spam, monopolization, and security risks. - -### Becoming a maintainer - -In late 2023, we will revisit this. We need to improve our understanding of how other projects are doing, their mechanisms to promote key contributors, and how they interact daily. - -We suspect this process might look similar to the [OpenSearch project](https://github.com/opensearch-project/.github/blob/main/MAINTAINERS.md#becoming-a-maintainer). - -## Common scenarios - -These are recurring ambiguous situations that new and existing maintainers may encounter. They serve as guidance. It is up to each maintainer to follow, adjust, or handle in a different manner as long as [our conduct is consistent](#uphold-code-of-conduct) - -### Contribution is stuck - -A contribution can get stuck often due to lack of bandwidth and language barrier. For bandwidth issues, check whether the author needs help. Make sure you get their permission before pushing code into their existing PR - do not create a new PR unless strictly necessary. - -For language barrier and others, offer a 1:1 chat to get them unblocked. Often times, English might not be their primary language, and writing in public might put them off, or come across not the way they intended to be. - -In other cases, you may have constrained capacity. Use `help-wanted` label when you want to signal other maintainers and external contributors that you could use a hand to move it forward. - -### Insufficient feedback or information - -When in doubt, use `need-more-information` or `need-customer-feedback` labels to signal more context and feedback are necessary before proceeding. You can also use `status/on-hold` label when you expect it might take a while to gather enough information before you can decide. - -Note that issues marked as `need-response` will be automatically closed after 3 weeks of inactivity. - -### Crediting contributions - -We credit all contributions as part of each [release note](https://github.com/aws-powertools/powertools-lambda-typescript/releases) as an automated process. If you find contributors are missing from the release note you're producing, please add them manually. - -### Is that a bug? - -A bug produces incorrect or unexpected results at runtime that differ from its intended behavior. Bugs must be reproducible. They directly affect customers experience at runtime despite following its recommended usage. - -Documentation snippets, examples, use of internal components, or unadvertised functionalities are not considered bugs. - -### Mentoring contributions - -Always favor mentoring issue authors to contribute, unless they're not interested or the implementation is sensitive (_e.g., complexity, time to release, etc._). - -Make use of `help-wanted` and `good-first-issue` to signal additional contributions the community can help. - -### Long running issues or PRs - -Try offering a 1:1 call in the attempt to get to a mutual understanding and clarify areas that maintainers could help. - -In the rare cases where both parties don't have the bandwidth or expertise to continue, it's best to use the `status/on-hold` label. By then, see if it's possible to break the PR or issue in smaller chunks, and eventually close if there is no progress. - -## Automation - -🚧 WIP 🚧 +> [!IMPORTANT] +> Maintainers' playbook moved: https://docs.powertools.aws.dev/lambda/typescript/latest/maintainers/ diff --git a/docs/contributing/conventions.md b/docs/contributing/conventions.md new file mode 100644 index 0000000000..517c556fff --- /dev/null +++ b/docs/contributing/conventions.md @@ -0,0 +1,45 @@ +--- +title: Conventions +description: General conventions and practices that are applicable throughout to Powertools for AWS Lambda (TypeScript) +--- + +## General terminology and practices + +These are common conventions we keep on building as the project gains new contributors and grows in complexity. + +As we gather more concrete examples, this page will have one section for each category to demonstrate a before and after. + +| Category | Convention | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Docstring** | We use [TypeDoc](https://typedoc.org){target="_blank"} annotations to help generate more readable API references. For public APIs, we always include at least one **Example** to ease everyone's experience when using an IDE. | +| **Style guide** | We use [Eslint](https://eslint.org){target="_blank"} and [Prettier](https://prettier.io){target="_blank"} to enforce beyond good practices. We use TypeScript types, function return types, and access modifiers to convey intent. | +| **Core utilities** | Core utilities always accept `serviceName` as a constructor parameter, can work in isolation, and are also available in other languages implementation. | +| **Utilities** | Utilities are not as strict as core and focus on community needs: development productivity, industry leading practices, etc. Both core and general utilities follow our [Tenets](https://docs.powertools.aws.dev/lambda/typescript/#tenets){target="_blank"}. | +| **Errors** | Specific errors thrown by Powertools live within utilities themselves and use `Error` suffix e.g. `IdempotencyKeyError`. | +| **Git commits** | We follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/){target="_blank"}. We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly. | +| **API documentation** | API reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise. | +| **Documentation** | We treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features. | + +## Repository structure + +The repository uses a monorepo structure managed using [npm workspaces](https://docs.npmjs.com/cli/v8/using-npm/workspaces). This allows us to keep all code in one place and share common dependencies. + +The Powertools for AWS Lambda (TypeScript) repository utilities live under the `packages/` directory. Each utility is a separate package and has its own `package.json` file. For example, the `@aws-lambda-powertools/logger` source code can be found under the `packages/logger/src` directory. + +Whenever possible, we use the same directory structure for all utilities. This makes it easier for contributors to navigate the repository and find what they need. Additionally, we try to share common runtime code between utilities to reduce maintenance overhead and runtime footprint. The shared runtime code lives under the `packages/commons/src` directory and is published to npm as the `@aws-lambda-powertools/commons` package. + +There are also a few other workspaces that are not utilities published to npm, but that still share dependencies and/or runtime code with the utilities. These workspaces are: + +* `docs/snippets`: contains the documentation code snippets +* `examples/*`: contains the example projects deployed via AWS CDK or AWS SAM +* `layers`: contains the code used to build and publish the [Lambda layers](../index.md#lambda-layer) + +## Testing definition + +We group tests in different categories + +| Test | When to write | Notes | Speed | +| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | +| Unit tests | Verify the smallest possible unit works. | Networking access is prohibited. Keep mocks and spies at minimum. | Fast (ms to few seconds at worst) | +| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. Also referred to as integration tests. | It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc. | Slow (minutes) | +| Performance tests | Ensure critical operations won't increase latency and costs to customers. | CI arbitrary hardware can make it flaky. We'll resume writing perf test after we revamp our unit/functional tests with internal utilities. | Fast to moderate (a few seconds to a few minutes) | \ No newline at end of file diff --git a/docs/contributing/getting_started.md b/docs/contributing/getting_started.md new file mode 100644 index 0000000000..d2166b4af7 --- /dev/null +++ b/docs/contributing/getting_started.md @@ -0,0 +1,86 @@ +--- +title: Your first contribution +description: All you need to know for your first contribution to Powertools for AWS Lambda (TypeScript) +--- + +Thank you for your interest in contributing to our project - we couldn't be more excited! + +
+```mermaid +graph LR + Learn["Learn about contributions"] --> Find["Find areas to work / get mentoring"] --> Work["Prepare pull request"] --> Closing["Take learnings with you"] +``` +End-to-end process +
+ +## Types of contributions + +We consider any contribution that help this project improve everyone's experience to be valid, as long as you agree with our [tenets](../index.md#tenets){target="_blank"}, [licensing](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/LICENSE){target="_blank"}, and [Code of Conduct](#code-of-conduct). + +Whether you're new contributor or a pro, we compiled a list of the common contributions to help you choose your first: + +!!! info "Please check [existing open](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc){target='_blank'}, or [recently closed](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed){target='_blank'} issues before creating a new one." + Each type link goes to their respective template, or Discord invite. + +| Type | Description | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Documentation](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=area%2Fdocumentation%2Ctriage&projects=aws-powertools%2F7&template=documentation_improvements.yml&title=Docs%3A+TITLE){target="_blank" rel="nofollow"} | Ideas to make user guide or API guide clearer. This includes typos, diagrams, tutorials, the lack of documentation, etc. | +| [Feature request](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2Ffeature-request%2Ctriage&projects=aws-powertools%2F7&template=feature_request.yml&title=Feature+request%3A+TITLE){target="_blank" rel="nofollow"} | New functionalities or enhancements that could help you, your team, or existing and future customers. Check out our [process to understand how we prioritize it](../roadmap.md#process){target="_blank"}. | +| [Design proposals](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2FRFC%2Ctriage&projects=aws-powertools%2F7&template=rfc.yml&title=RFC%3A+TITLE){target="_blank" rel="nofollow"} | Request for Comments (RFC) including user experience (UX) based on a feature request to gather the community feedback, and demonstrate the art of the possible. | +| [Bug report](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2Fbug%2Ctriage&projects=aws-powertools%2F7&template=bug_report.yml&title=Bug%3A+TITLE){target="_blank" rel="nofollow"} | A runtime error that is reproducible whether you have an idea how to solve it or not. | +| [Advocacy](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=community-content&projects=aws-powertools%2F7&template=share_your_work.yml&title=%5BI+Made+This%5D%3A+%3CTITLE%3E){target="_blank" rel="nofollow"} | Share what you did with Powertools for AWS Lambda. Blog posts, workshops, presentation, sample applications, podcasts, etc. | +| [Public reference](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=customer-reference&projects=aws-powertools%2F7&template=support_powertools.yml&title=%5BSupport+Powertools+for+AWS+Lambda+%28TypeScript%29%5D%3A+%3Cyour+organization+name%3E){target="_blank" rel="nofollow"} | Become a public reference to share how you're using Powertools for AWS Lambda at your organization. | +| [Discussions](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"} | Kick off a discussion on Discord, introduce yourself, and help respond to existing questions from the community. | +| [Maintenance](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2Finternal%2Ctriage&projects=aws-powertools%2F7&template=maintenance.yml&title=Maintenance%3A+TITLE){target="_blank" rel="nofollow"} | Suggest areas to address technical debt, governance, and anything internal. Generally used by maintainers and contributors. | + +## Finding contributions to work on + +[Besides suggesting ideas](#types-of-contributions) you think it'll improve everyone's experience, these are the most common places to find work: + +| Area | Description | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Help wanted issues](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted+sort%3Aupdated-desc){target="_blank" rel="nofollow"} | These are triaged areas that we'd appreciate any level of contribution - from opinions to actual implementation. | +| [Missing customer feedback issues](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aopen+is%3Aissue+label%3Aneed-customer-feedback+sort%3Aupdated-desc+){target="_blank" rel="nofollow"} | These are items we'd like to hear from more customers before making any decision. Sharing your thoughts, use case, or asking additional questions are great help. | +| [Pending design proposals](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2FRFC%2Ctriage&projects=aws-powertools%2F7&template=rfc.yml&title=RFC%3A+TITLE){target="_blank" rel="nofollow"} | These are feature requests that initially look good but need a RFC to enrich the discussion by validating user-experience, tradeoffs, and highlight use cases. | +| [Backlog items](https://github.com/orgs/aws-powertools/projects/7/views/3?query=is%3Aopen+sort%3Aupdated-desc){target="_blank" rel="nofollow"} | We use GitHub projects to surface what we're working on, needs triage, etc. This view shows items we already triaged but don't have the bandwidth to tackle them just yet. | +| [Documentation](https://docs.powertools.aws.dev/lambda/typescript/latest/){target="_blank"} | Documentation can always be improved. Look for areas that a better example, or a diagram, or more context helps everyone - keep in mind a diverse audience and English as a second language folks. | +| [Participate in discussions](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"} | There's always a discussion that could benefit others in the form of documentation, blog post, etc. | +| [Roadmap](../roadmap.md){target="_blank"} | Some roadmap items need a RFC to discuss design options, or gather customers use case before we can prioritize it. | +| Build a sample application | Using Powertools for AWS Lambda in different contexts will give you insights on what could be made easier, which documentation could be enriched, and more. | + +!!! question "Still couldn't find anything that match your skill set?" + Please reach out on [Discord](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"}, specially if you'd like to get mentoring for a task you'd like to take but you don't feel ready yet :blush: + + Contributions are meant to be bi-directional. There's always something we can learn from each other. + +## Sending a pull request + +!!! note "First time creating a Pull Request? Keep [this document handy.](https://help.github.com/articles/creating-a-pull-request/){target='blank' rel='nofollow'}" + +Before sending us a pull request, please ensure that: + +* You are working against the latest source on the **main** branch, unless instructed otherwise. +* You check existing [open, and recently merged](https://github.com/aws-powertools/powertools-lambda-typescript/pulls?q=is%3Apr+is%3Aopen%2Cmerged+sort%3Aupdated-desc){target="_blank" rel="nofollow"} pull requests to make sure someone else hasn't addressed the problem already. +* You discuss and agree your proposed changes under [an existing issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aopen+is%3Aupdated-desc) or a [new issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose){target="_blank" rel="nofollow"} before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful. +* Create a new branch named after the change you are contributing _e.g._ `feat/logger-debug-sampling` + +**Ready?** + +These are the steps to send a pull request: + +1. Make sure that all formatting, linting, and tests tasks run as git pre-commit & pre-push hooks are passing. +2. Commit to your fork using clear commit messages. Don't worry about typos or format, we squash all commits during merge. +3. Send us a pull request with a [conventional semantic title](https://github.com/aws-powertools/powertools-lambda-typescript/pull/1744) - see full list of scopes and actions [here](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/.github/semantic.yml#L2). +4. Fill in the areas pre-defined in the pull request body to help expedite reviewing your work. +5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. + +## Code of Conduct + +!!! info "This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct){target='_blank'}" + +For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact + with any additional questions or comments. + +## Security issue notifications + +If you discover a potential security issue in this project, we kindly ask you to notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. \ No newline at end of file diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md new file mode 100644 index 0000000000..6960bfcf88 --- /dev/null +++ b/docs/contributing/setup.md @@ -0,0 +1,72 @@ +--- +title: Development environment +description: Setting up your development environment for contribution +--- + +[![Join our Discord](https://dcbadge.vercel.app/api/server/B8zZKbbyET)](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"} + +This page describes how to setup your development environment (Cloud or locally) to contribute to Powertools for AWS Lambda (TypeScript). + +
+```mermaid +graph LR + Dev["Development environment"] --> Quality["Run quality checks locally"] --> PR["Prepare pull request"] --> Collaborate +``` +End-to-end process +
+ +## Requirements + +!!! question "First time contributing to an open-source project ever?" + Read this [introduction on how to fork and clone a project on GitHub](https://docs.github.com/en/get-started/quickstart/contributing-to-projects){target="_blank" rel="nofollow"}. + +Unless you're using the pre-configured Cloud environment, you'll need the following installed: + +* [GitHub account](https://github.com/join){target="_blank" rel="nofollow"}. You'll need to be able to fork, clone, and contribute via pull request. +* [Node.js 18.x](https://nodejs.org/download/release/latest-v18.x/){target="_blank" rel="nofollow"}. The repository contains an `.nvmrc` file, so if you use tools like [nvm](https://github.com/nvm-sh/nvm#nvmrc), [fnm](https://github.com/Schniz/fnm) you can switch version quickly. +* [npm 9.x](https://www.npmjs.com/). We use it to install dependencies and manage the workspaces. +* [Docker](https://docs.docker.com/engine/install/){target="_blank" rel="nofollow"}. We use it to run documentation, and non-JavaScript tooling. +* [Fork the repository](https://github.com/aws-powertools/powertools-lambda-typescript/fork). You'll work against your fork of this repository. + +??? note "Additional requirements if running end-to-end tests" + + * [AWS Account bootstrapped with CDK](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html){target="_blank"} + * [AWS CLI installed and configured](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + +## Cloud environment + +!!! warning "A word of caution" + Before using a Cloud environment, be mindful of the pricing structure. You can find more information about each service pricing respectively on [Gitpod](https://www.gitpod.io/pricing){target="_blank" rel="nofollow"} and [GitHub Codespaces](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces){target="_blank" rel="nofollow"} pages. When in doubt, use the local environment below. + +Once provisioned, each Cloud environment will come with all development dependencies and tools you'll need to contribute already installed. + +### Gitpod + +To use a pre-configured Gitpod environment, create or login to a Gitpod account, then replace `YOUR_USERNAME` with your GitHub username or organization. + +```bash +https://gitpod.io/#https://github.com/YOUR_USERNAME/powertools-lambda-typescript #(1)! +``` + +1. For example, if your username is `octocat`, then the final URL should be `https://gitpod.io/#https://github.com/octocat/powertools-lambda-typescript` + +### GitHub Codespaces + +To use a pre-configured GitHub Codespaces environment, navigate to your fork of the repository, then click on the green `Code` button, and select `Create codespace on ` under the `Codespaces` tab (where `` is the branch you want to work on). + +## Local environment + +> Assuming you've got all [requirements](#requirements). + +You can use `npm run setup-local` to install all dependencies locally and setup pre-commit hooks. + +!!! note "Curious about what `setup-local` does under the hood?" + We use npm scripts to [automate common tasks](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/package.json#L24){target="_blank" rel="nofollow"} locally and in Continuous Integration environments. + +## Local documentation + +You might find useful to run both the documentation website and the API reference locally while contributing: + +* **Docs website**: `npm run docs-runLocalDocker` + * If this is your first time running the docs, you need to build the image: `npm run docs-buildDockerImage` +* **API reference**: `npm run docs-api-build-run` \ No newline at end of file diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md new file mode 100644 index 0000000000..6412297499 --- /dev/null +++ b/docs/contributing/testing.md @@ -0,0 +1,103 @@ +--- +title: Testing +description: How to write tests for Powertools for AWS Lambda (TypeScript) +--- + +## General practices + +As discussed in the [conventions](./conventions.md) page, we have different types of tests that aim to verify different aspects of the code. + +Tests are defined alongside the code they test, and can be found under the `tests` folder of each module. For example, the tests for the `@aws-lambda-powertools/logger` module can be found under `packages/logger/tests`. + +Each test type has its own folder, and each test file is named after the feature it tests. For example, the tests for the `@aws-lambda-powertools/logger` module can be found under `packages/logger/tests/unit` and `packages/logger/tests/e2e`. + +Tests are written using [Jest](https://jestjs.io) and are grouped into categories. You can run each group separately or all together thanks to [jest-runner-groups](https://www.npmjs.com/package/jest-runner-groups). + +Each test file needs to be tagged with the proper group, otherwise, it won't be executed. The group is defined in the header of the file, and it follows this convention: + +```typescript +/** + * Tests metrics + * + * @group unit// + */ +``` + +The test file should contain one or more tests organized using the `describe` and `it` functions. Each test should be named after the feature it tests, and should be as descriptive as possible. For example, the test for the `Logger` class `info` method is named `should log info message`. + +```typescript +describe('Class: Logger', () => { + describe('Method: info', () => { + it('should log info message', () => { + // ... + }) + }) +}) +``` + +Single tests should be as simple as possible, and should follow the Prepare, Act, Assess pattern. For example, the test from the previous example should look like this: + +```typescript +describe('Class: Logger', () => { + describe('Method: info', () => { + it('should log info message', () => { + // Prepare + const logger = new Logger() + + // Act + logger.info('test') + + // Assess + expect(logger.info).toHaveBeenCalledWith('test') + }) + }) +}) +``` + +## Unit tests + +Unit tests are used to verify the smallest possible unit of code works as expected. They are fast to run and should be used to test the core logic of the code. They should not test external dependencies, such as network calls, and should use mocks and spies as needed to verify the code behaves as expected. + +When writing unit tests, you should follow the same conventions we use for the code. For example, each test file should correspond to a single discrete feature such as a single high-level function, class, or middleware. For example, the `Logger` class for the `@aws-lambda-powertools/logger` module has a single test file named `logger.test.ts`. + +To run unit tests, you can use of the following commands from the root folder: + +* `npm test -ws` to run all the unit tests for all the modules sequentially +* `npm run test:parallel` to run all the unit tests for all the modules in parallel +* `npm test -w packages/metrics` to run all the unit tests for the `metrics` module +* `npm run jest -w packages/metrics -- --group=unit/metrics/middleware` to run all the unit tests for the `metrics` module that are tagged with the `unit/metrics/middleware` group + + +We enforce 100% code coverage for unit tests. The test command will fail if the coverage is not 100% both on your local machine and in CI. + +## Integration tests + +Integration tests are used to verify that the code works as expected when deployed to AWS. They are slower than unit tests, and should be used to test the code in a real environment. They should test the code as a whole, including external dependencies such as network calls, and should not use mocks and spies. + +When writing integration tests, you should follow the same conventions used for existing tests. For example, each test file should correspond to an utility and a specific usage type. For example, the test for the middleware usage for the `@aws-lambda-powertools/logger` module has a single test file named `basicFeatures.middy.test.ts`. + +!!! warning "A word of caution" + Running integration tests will deploy AWS resources in your AWS account, which might incur costs. The cost from **some services** are covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but not all of them. We recommend you to use a dedicated AWS account for testing purposes, and when in doubt, let the CI on our repository run the tests for you. + +To run integration tests you'll need to set up an AWS account and obtain credentials as described in the [prerequisites](./setup.md#requirements). Once ready, you can use of the following commands from the root folder: + +* `npm test:e2e -ws` to run all the integration tests for all the modules sequentially +* `test:e2e:parallel` to run all the integration tests for all the modules in parallel +* `npm test:e2e -w packages/metrics` to run all the integration tests for the `metrics` module +* `npm run test:e2e:nodejs18x -w packages/metrics` to run all the integration tests for the `metrics` module using the `nodejs18x` runtime + +The tests will deploy the necessary AWS resources using AWS CDK, and will run the Lambda functions using the AWS SDK. After that, the tests will verify the Lambda functions behave as expected by checking logs, metrics, traces, and other resources as needed. Finally, the tests will destroy all the AWS resources created at the beginning. + +Below is a diagram that shows the flow of the integration tests: + +```mermaid +sequenceDiagram + Dev Environment / CI->>+Jest: npm run test:e2e + Jest-->Jest: Synthetize CloudFormation Stack + Jest->>+AWS: Deploy Stack + Jest->>+AWS: Invoke Lambda function + AWS->>Jest: Report logs / results + Jest-->Jest: Assert logs/result + Jest->>+AWS: Destroy Stack + Jest->>+Dev Environment / CI: show test results +``` \ No newline at end of file diff --git a/docs/maintainers.md b/docs/maintainers.md new file mode 100644 index 0000000000..d5608f1ac8 --- /dev/null +++ b/docs/maintainers.md @@ -0,0 +1,338 @@ +--- +title: Maintainers playbook +description: Playbook for active maintainers in Powertools for AWS Lambda (TypeScript) +--- + +## Overview + +!!! note "Please treat this content as a living document." + +This is document explains who the maintainers are, their responsibilities, and how they should be doing it. If you're interested in contributing, see [Contributing](./contributing/getting_started.md) document. + +## Current Maintainers + +| Maintainer | GitHub ID | Affiliation | +| ------------------ | --------------------------------------------------------------------------- | ----------- | +| Andrea Amorosi | [dreamorosi](https://github.com/dreamorosi){target="_blank" rel="nofollow"} | Amazon | +| Alexander Schueren | [am29d](https://github.com/am29d){target="_blank" rel="nofollow"} | Amazon | +| Simon Thulbourn | [sthulb](https://github.com/sthulb){target="_blank" rel="nofollow"} | Amazon | + +## Emeritus + +Previous active maintainers who contributed to this project. + +| Maintainer | GitHub ID | Affiliation | +| -------------------------- | ------------------------------------------------------------------------------- | ----------- | +| Sara Gerion | [saragerion](https://github.com/saragerion){target="_blank" rel="nofollow"} | Amazon | +| Florian Chazal | [flochaz](https://github.com/flochaz){target="_blank" rel="nofollow"} | Amazon | +| Chadchapol Vittavutkarnvej | [ijemmy](https://github.com/ijemmy){target="_blank" rel="nofollow"} | Booking.com | +| Alan Churley | [alan-churley](https://github.com/alan-churley){target="_blank" rel="nofollow"} | CloudCall | +| Michael Bahr | [bahrmichael](https://github.com/bahrmichael){target="_blank" rel="nofollow"} | Stedi | + +## Labels + +These are the most common labels used by maintainers to triage issues, pull requests (PR), and for project management: + +| Label | Usage | Notes | +| -------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| triage | New issues that require maintainers review | Issue template | +| area/documentation | Improvements or additions to documentation | Examples/Readme files; Doc additions, fixes, etc.; | +| area/logger | Items related to the Logger Utility | PR automation | +| area/metrics | Items related to the Metrics Utility | PR automation | +| area/tracer | Items related to the Tracer Utility | PR automation | +| area/idempotency | Items related to the Idempotency Utility | PR automation | +| area/parameters | Items related to the Parameters Utility | PR automation | +| area/commons | Items related to the Commons Utility | PR automation | +| area/jmespath | Items related to the JMESPath Utility | PR automation | +| area/validation | Items related to the Validation Utility | PR automation | +| area/batch | Items related to the Batch Processing Utility | PR automation | +| area/parser | Items related to the Parser Utility | PR automation | +| area/automation | Items related to automation like GitHub workflows or CI/CD | PR automation | +| area/layers | Items related to the Lambda Layers pipeline | PR automation | +| size/XS | PRs between 0-9 LOC | PR automation | +| size/S | PRs between 10-29 LOC | PR automation | +| size/M | PRs between 30-99 LOC | PR automation | +| size/L | PRs between 100-499 LOC | PR automation | +| size/XL | PRs between 500-999 LOC, often PRs that grown with feedback | PR automation | +| size/XXL | PRs with 1K+ LOC, largely documentation related | PR automation | +| customer-reference | Authorization to use company name in our documentation | Public Relations | +| community-content | Suggested content to feature in our documentation | Public Relations | +| do-not-merge | PRs that are blocked for varying reasons | Timeline is uncertain | +| type/bug | Unexpected, reproducible and unintended software behavior | PR/Release automation; Doc snippets are excluded; | +| type/bug-upstream | Bug caused by upstream dependency | | +| type/not-a-bug | New and existing bug reports incorrectly submitted as bug | Analytics | +| type/deprecation | This item contains code deprecation | | +| type/duplicate | This issue is a duplicate of an existing one | Analytics | +| type/feature-request | Issue requesting new or enhancements to existing features | Issue template | +| type/feature | PRs that introduce new features | PR automation | +| type/enhancement | PRs that introduce minor changes, usually to existing features | PR automation | +| type/RFC | Technical design documents related to a feature request | | +| type/internal | PRs that introduce changes in governance, tech debt and chores (linting setup, baseline, etc.) | PR automation | +| type/tests | PRs that add or change tests | PR automation | +| type/dependencies | Changes that touch dependencies, e.g. Dependabot, etc. | Issues/PR automation | +| type/breaking-change | Changes that will cause customer impact and need careful triage | | +| status/blocked | Items which progress is blocked by external dependency or reason | | +| status/confirmed | Items with clear scope and that are ready for implementation | | +| status/discussing | Items that need to be discussed, elaborated, or refined | | +| status/on-hold | Items that are on hold and will be revisited in the future | | +| status/pending-release | Merged changes that will be available soon | Release automation auto-closes/notifies it | +| status/completed | Items that are complete and have been merged and/or shipped | | +| status/rejected | This is something we will not be working on. At least, not in the measurable future | | +| status/pending-close-response-required | This issue will be closed soon unless the discussion moves forward | Stale Automation | +| revisit-in-3-months | Blocked issues/PRs that need to be revisited | Often releated to `need-customer-feedback`, prioritization, etc. | +| good-first-issue | Something that is suitable for those who want to start contributing | | +| help-wanted | Tasks you want help from anyone to move forward | Bandwidth, complex topics, etc. | +| need-customer-feedback | Tasks that need more feedback before proceeding | 80/20% rule, uncertain, etc. | +| need-more-information | Missing information before making any calls | Signal that investigation or answers are needed | +| need-response | Requires a response from a customer and might be automatically closed if none is received | Marked as stale after 2 weeks, and closed after 3 | +| need-issue | PR is missing a related issue for tracking change | | + +## Maintainer Responsibilities + +Maintainers are active and visible members of the community, and have [maintain-level permissions on a repository](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization){target="_blank" rel="nofollow"}. Use those privileges to serve the community and evolve code as follows. + +Be aware of recurring ambiguous situations and [document them](#common-scenarios) to help your fellow maintainers. + +### Uphold Code of Conduct + +Model the behavior set forward by the [Code of Conduct](https://github.com/aws-powertools/powertools-lambda-typescript/blob/develop/CODE_OF_CONDUCT.md){target="_blank"} and raise any violations to other maintainers and admins. There could be unusual circumstances where inappropriate behavior does not immediately fall within the [Code of Conduct](https://github.com/aws-powertools/powertools-lambda-typescript/blob/develop/CODE_OF_CONDUCT.md){target="_blank"}. + +These might be nuanced and should be handled with extra care - when in doubt, do not engage and reach out to other maintainers and admins. + +### Prioritize Security + +Security is your number one priority. Maintainer's Github keys must be password protected securely and any reported security vulnerabilities are addressed before features or bugs. + +Note that this repository is monitored and supported 24/7 by Amazon Security, see [Reporting a Vulnerability](https://github.com/aws-powertools/powertools-lambda-typescript/blob/develop/SECURITY.md){target="_blank"} for details. + +### Review Pull Requests + +Review pull requests regularly, comment, suggest, reject, merge and close. Accept only high quality pull-requests. Provide code reviews and guidance on incoming pull requests. + +PRs are [labeled](#labels) based on file changes and semantic title. Pay attention to whether labels reflect the current state of the PR and correct accordingly. + +Use and enforce [semantic versioning](https://semver.org/) pull request titles, as these will be used for [CHANGELOG](./changelog.md) and [Release notes](https://github.com/aws-powertools/powertools-lambda-typescript/releases) - make sure they communicate their intent at the human level. + +For issues linked to a PR, make sure `status/pending-release` label is applied to them when merging. [Upon release](#releasing-a-new-version), these issues will be notified which release version contains their change. + +See [Common scenarios](#common-scenarios) section for additional guidance. + +### Triage New Issues + +Manage [labels](#labels), review issues regularly, and create new labels as needed by the project. Remove `triage` label when you're able to confirm the validity of a request, a bug can be reproduced, etc. Give priority to the original author for implementation, unless it is a sensitive task that is best handled by maintainers. + +Make sure issues are assigned to our [board of activities](https://github.com/orgs/awslabs/projects/7/) and have the right [status](https://docs.powertools.aws.dev/lambda/typescript/latest/roadmap/#roadmap-status-definition). + +Use our [labels](#labels) to signal good first issues to new community members, and to set expectation that this might need additional feedback from the author, other customers, experienced community members and/or maintainers. + +Be aware of [casual contributors](https://opensource.com/article/17/10/managing-casual-contributors) and recurring contributors. Provide the experience and attention you wish you had if you were starting in open source. + +See [Common scenarios](#common-scenarios) section for additional guidance. + +### Triage Bug Reports + +Be familiar with [our definition of bug](#is-that-a-bug). If it's not a bug, you can close it or adjust its title and labels - always communicate the reason accordingly. + +For bugs caused by upstream dependencies, replace `type/bug` with `type/bug-upstream` label. Ask the author whether they'd like to raise the issue upstream or if they prefer us to do so. + +Assess the impact and make the call on whether we need an emergency release. Contact other [maintainers](#current-maintainers) when in doubt. + +See [Common scenarios](#common-scenarios) section for additional guidance. + +### Triage RFCs + +RFC is a collaborative process to help us get to the most optimal solution given the context. Their purpose is to ensure everyone understands what this context is, their trade-offs, and alternative solutions that were part of the research before implementation begins. + +Make sure you ask these questions in mind when reviewing: + +- Does it use our [RFC template](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=RFC%2Ctriage&template=rfc.yml&title=RFC%3A+TITLE)? +- Does the match our [Tenets](https://docs.powertools.aws.dev/lambda/typescript/latest/#tenets)? +- Does the proposal address the use case? If so, is the recommended usage explicit? +- Does it focus on the mechanics to solve the use case over fine-grained implementation details? +- Can anyone familiar with the code base implement it? +- If approved, are they interested in contributing? Do they need any guidance? +- Does this significantly increase the overall project maintenance? Do we have the skills to maintain it? +- If we can't take this use case, are there alternative projects we could recommend? Or does it call for a new project altogether? + +When necessary, be upfront that the time to review, approve, and implement a RFC can vary - see [Contribution is stuck](#contribution-is-stuck). Some RFCs may be further updated after implementation, as certain areas become clearer. + +Some examples using our initial and new RFC templates: [#447](https://github.com/aws-powertools/powertools-lambda-typescript/issues/447) + +### Releasing a new version + +Firstly, make sure all the PRs that you want to include in the release are merged into the `main` banch. + +Next, run the integration tests one last time to make sure everything is working as expected. See [Run end to end tests](#run-end-to-end-tests) for more details. + +**Looks good, what's next?** + +Kickoff the `Make Release` workflow with the intended version - this might take around 20m-25m to complete. + +Once complete, you can start drafting the release notes to let customers know **what changed and what's in it for them (a.k.a why they should care)**. We have guidelines in the release notes section so you know what good looks like. + +> **NOTE**: Documentation might take a few minutes to reflect the latest version due to caching and CDN invalidations. + +#### Release process visualized + +Every release makes dozens of checks, linting, canaries and deployments - all of these are automated. + +This is a close visual representation of the main steps (GitHub Actions UI should be the source of truth), along with the approximate time it takes for each key step to complete. + + + +```mermaid +gantt + +title Release process +dateFormat HH:mm +axisFormat %H:%M + +Release start : milestone, m1, 10:00,2m + +section QA + Quality checks : active, 2.4m + +section Build + Bundle release artifact (CJS) : active, 39s + +section Git release + Bump package version : active, 8s + Package release : active, 8s + Git Tag : active, 8s + Push Tag : active, 8s + +section Release + Attest build : active, 8s + Sign attestation : active, attestation, 10:06, 8s + Publish npm.js : active, npm, after attestation, 29s + +npmjs.com release : milestone, m2, 10:06,1s + +section Layer release + Build : active, layer_build, 10:08, 6m + Deploy Beta : active, layer_beta, after layer_build, 4.3m + Run Canary Test : active, layer_canary, after layer_beta, 1.4m + Deploy Prod : active, layer_prod, after layer_canary, 4.3m + +Layer release : milestone, m3, 10:24,1s + +section Docs + Create commit (Layer ARN) : active, 10:24, 8s + Release versioned docs : active, 2.4m + +Documentation release : milestone, m4, 10:26,1m + +Release complete : milestone, m5, 10:26, 2m +``` + +#### Drafting release notes + +Visit the [Releases page](https://github.com/aws-powertools/powertools-lambda-typescript/releases) and choose the edit pencil button. + +Make sure the `tag` field reflects the new version you're releasing, the target branch field is set to `main`, and `release title` matches your tag e.g., `v1.14.1`. + +You'll notice we group all changes based on their [labels](#labels) like `type/feature`, `type/bug`, `area/documentation`, etc. + +**I spotted a typo or incorrect grouping - how do I fix it?** + +Edit the respective PR title and update their [labels](#labels). Then run the [Release Drafter workflow](https://github.com/aws-powertools/powertools-lambda-typescript/**actions**/workflows/release-drafter.yml) to update the Draft release. + +!!! note + This won't change the CHANGELOG as the merge commit is immutable. Don't worry about it. We'd only rewrite git history only if this can lead to confusion and we'd pair with another maintainer. + +**All looking good, what's next?** + +The best part comes now. Replace the placeholder `[Human readable summary of changes]` with what you'd like to communicate to customers what this release is all about. Rule of thumb: always put yourself in the customers shoes. + +These are some questions to keep in mind when drafting your first or future release notes: + +- Can customers understand at a high level what changed in this release? +- Is there a link to the documentation where they can read more about each main change? +- Are there any graphics or [code snippets](https://carbon.now.sh/) that can enhance readability? +- Are we calling out any key contributor(s) to this release? + - All contributors are automatically credited, use this as an exceptional case to feature them + +Once you're happy, hit `Publish release` πŸŽ‰πŸŽ‰πŸŽ‰. + +This will kick off the [Post Release workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/post-release.yml) and within a few minutes you should see all issues labeled as `status/pending-release` notified of the new release and labeled as `status/completed`. + +### Run end to end tests + +!!! note + We are planning to automate this process in the future so that tests are run automatically when a PR is merged, see [#1149](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1149){target="_blank" rel="nofollow"} + +E2E tests should be ran before every merge to `main` or manually via [Run e2e Tests workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/run-e2e-tests.yml) before making a release. + +To run locally, you need [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites) and an [account bootstrapped](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) (`cdk bootstrap`). With a default AWS CLI profile configured, or `AWS_PROFILE` environment variable set, run `make e2e tests`. + +For more information on how the tests are structured and how they can be run locally, see [Integration Tests](./contributing/testing.md). + +### Releasing a documentation hotfix + +You can rebuild the latest documentation without a full release via this [GitHub Actions Workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/rebuild-latest-docs.yml). Choose `Run workflow`, keep `main` as the branch, and input the latest Powertools for AWS Lambda (TypeScript) version available. + +This workflow will update both user guide and API documentation. + +### Maintain Overall Health of the Repo + +Keep the `main` branch at production quality at all times. Backport features as needed. Cut release branches and tags to enable future patches. + +### Manage Roadmap + +See [Roadmap section](https://docs.powertools.aws.dev/lambda/typescript/latest/roadmap/) + +Ensure the repo highlights features that should be elevated to the project roadmap. Be clear about the feature’s status, priority, target version, and whether or not it should be elevated to the roadmap. + +### Add Continuous Integration Checks + +Add integration checks that validate pull requests and pushes to ease the burden on Pull Request reviewers. Continuously revisit areas of improvement to reduce operational burden in all parties involved. + +### Negative Impact on the Project + +Actions that negatively impact the project will be handled by the admins, in coordination with other maintainers, in balance with the urgency of the issue. Examples would be [Code of Conduct](https://github.com/aws-powertools/powertools-lambda-typescript/blob/develop/CODE_OF_CONDUCT.md){target="_blank"} violations, deliberate harmful or malicious actions, spam, monopolization, and security risks. + +### Becoming a maintainer + +We need to improve our understanding of how other projects are doing, their mechanisms to promote key contributors, and how they interact daily. + +We suspect this process might look similar to the [OpenSearch project](https://github.com/opensearch-project/.github/blob/main/MAINTAINERS.md#becoming-a-maintainer){target="_blank" rel="nofollow"} and will revisit this in late 2024. + +## Common scenarios + +These are recurring ambiguous situations that new and existing maintainers may encounter. They serve as guidance. It is up to each maintainer to follow, adjust, or handle in a different manner as long as [our conduct is consistent](#uphold-code-of-conduct) + +### Contribution is stuck + +A contribution can get stuck often due to lack of bandwidth and language barrier. For bandwidth issues, check whether the author needs help. Make sure you get their permission before pushing code into their existing PR - do not create a new PR unless strictly necessary. + +For language barrier and others, offer a 1:1 chat to get them unblocked. Often times, English might not be their primary language, and writing in public might put them off, or come across not the way they intended to be. + +In other cases, you may have constrained capacity. Use `help-wanted` label when you want to signal other maintainers and external contributors that you could use a hand to move it forward. + +### Insufficient feedback or information + +When in doubt, use `need-more-information` or `need-customer-feedback` labels to signal more context and feedback are necessary before proceeding. You can also use `revisit-in-3-months` label when you expect it might take a while to gather enough information before you can decide. + +Note that issues marked as `need-response` will be automatically closed after 3 weeks of inactivity. + +### Crediting contributions + +We credit all contributions as part of each [release note](https://github.com/aws-powertools/powertools-lambda-typescript/releases){target="_blank"} as an automated process. If you find contributors are missing from the release note you're producing, please add them manually. + +### Is that a bug? + +A bug produces incorrect or unexpected results at runtime that differ from its intended behavior. Bugs must be reproducible. They directly affect customers experience at runtime despite following its recommended usage. + +Documentation snippets, use of internal components, or unadvertised functionalities are not considered bugs. + +### Mentoring contributions + +Always favor mentoring issue authors to contribute, unless they're not interested or the implementation is sensitive (_e.g., complexity, time to release, etc._). + +Make use of `help-wanted` and `good-first-issue` to signal additional contributions the community can help. + +### Long running issues or PRs + +Try offering a 1:1 call in the attempt to get to a mutual understanding and clarify areas that maintainers could help. + +In the rare cases where both parties don't have the bandwidth or expertise to continue, it's best to use the `status/on-hold` or `revisit-in-3-months` labels. After some time has passed, see if it's possible to break the PR or issue in smaller chunks, and eventually close if there is no progress. \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md index 3e7ac97cf7..1774b5323f 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,40 +1,46 @@ ## Overview -This is our public roadmap that outlines the high level direction we are working towards, namely [Themes](#themes). We update this document when our priorities change, however security and stability is always our top priority. +Our public roadmap outlines the high level direction we are working towards, namely [Themes](#themes). We update this document when our priorities change: security and stability is our top priority. -[See our latest list of activities Β»](https://github.com/orgs/aws-powertools/projects/7){target="_blank"} +!!! info "For most up-to-date information, see our [board of activities](https://github.com/orgs/aws-powertools/projects/7/views/3?query=is%3Aopen+sort%3Aupdated-desc){target="_blank"}." ## Themes -!!! info "Operational Excellence is priority number 1." +Operational Excellence is priority number 1. This means bug fixing, stability, security, customer's support, and governance will take precedence above all else. -Themes are key activities maintainers are focusing on, besides bug reports. These are updated periodically and you can get an idea of the overall progress in the [Milestones section](https://github.com/aws-powertools/powertools-lambda-typescript/milestones){target="_blank"}. +**What are themes?** + +They are key activities maintainers are focusing on. These are updated periodically and you can find the latest [under Themes in our GitHub Milestones](https://github.com/aws-powertools/powertools-lambda-typescript/milestones){target="_blank"}. ### Feature Parity We want to close the gap between this version of Powertools for AWS Lambda and the [Python version](https://github.com/aws-powertools/powertools-lambda-python). This means that in the fullness of time, we want to have the same or equivalent features in both versions. -In the first half of 2023 we have released the [Parameters utility](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/10), then in July we have released public betas for [Idempotency](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/7) and [Batch Processing](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/13). We are eager to hear your feedback on these new features, so please try them out and let us know what you think! +In 2023 we have released three the utilities, first as public betas and then as generally available: + +- [x] [Parameters](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parameters/) +- [x] [Idempotency](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/idempotency/) +- [x] [Batch Processing](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/batch/) -For the remaining of 2023, we are considering implementing one or more of the following utilities (in no particular order): +Over the next quarter, we are considering implementing one or more of the following utilities (in no particular order): -* Validation (Status: [RFC](https://github.com/aws-powertools/powertools-lambda-typescript/issues/508)) -* Parser (Status: [RFC](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1334)) -* Event Handler (Status: [RFC](https://github.com/aws-powertools/powertools-lambda-typescript/issues/413)) +- [ ] Parser (Status: [RFC Finalized](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1334) - Implementation: [In Progress](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/15)) +- [ ] Validation (Status: [RFC In Progress](https://github.com/aws-powertools/powertools-lambda-typescript/issues/508)) +- [ ] Event Handler (Status: [RFC In Progress](https://github.com/aws-powertools/powertools-lambda-typescript/issues/413)) If any of these utilities are important to you, please let us know by upvoting the issue, leaving a comment under the RFCs, or by joining the discussion in our [Discord community](https://discord.gg/B8zZKbbyET){target="_blank"}. ### Version 2 release -Over the past year, we have gathered a number of feature requests and improvements that we want to implement but that are not backwards compatible with the current API surface. We are planning to release a new major version of the library by the end of 2023, which will include some of these changes. +Over the past year, we have gathered a number of feature requests and improvements that we want to implement but that are not backwards compatible with the current API surface. We are going to release our next major version (v2) by the end of 2023, which will include some of these changes: -The following are some of the changes we are considering: +- [x] **ES Modules support ([#521](https://github.com/aws-powertools/powertools-lambda-typescript/issues/521))** - Thanks to the work of the community we have been able to validate the feasibility of dual support for CommonJS and ES Modules. We are currently working on a plan to implement this. +- [x] **TypeScript 5.x support ([#1375](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1375))** - This new version of TypeScript brings breaking changes to the experimental decorators API, which we use in our core utilities. We need to investigate the impact of this change and how to best support it. +- [x] **Support for 3rd party observability providers ([#1500](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1500))** - Many of our customers would like to use Powertools for AWS to send logs, traces, and metrics to providers other than Amazon CloudWatch. At the moment we are investigating the feasibility of this for the Logger utility, while the Python version of Powertools for AWS Lambda is considering this also for Tracer and Metrics. -* **ES Modules support ([#521](https://github.com/aws-powertools/powertools-lambda-typescript/issues/521))** - Thanks to the work of the community we have been able to validate the feasibility of dual support for CommonJS and ES Modules. We are currently working on a plan to implement this. -* **TypeScript 5.x support ([#1375](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1375))** - This new version of TypeScript brings breaking changes to the experimental decorators API, which we use in our core utilities. We need to investigate the impact of this change and how to best support it. -* **Support for 3rd party observability providers ([#1500](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1500))** - Many of our customers would like to use Powertools for AWS to send logs, traces, and metrics to providers other than Amazon CloudWatch. At the moment we are investigating the feasibility of this for the Logger utility, while the Python version of Powertools for AWS Lambda is considering this also for Tracer and Metrics. +You can find the full list of changes in the [v2 RFC](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1714) and follow the progress in the [v2 milestone](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/12). -We have not yet decided on the final list of features that will be included in this release, if you have any suggestions please let us know by commenting on [this discussion](https://github.com/aws-powertools/powertools-lambda-typescript/discussions/1269) or upvoting existing suggestions. +Just like for the feature parity, if you have any feedback or would like to contribute to the discussion, please leave a comment in the RFC or join the discussion in our [Discord community](https://discord.gg/B8zZKbbyET){target="_blank"}. ### Improve operational excellence @@ -52,15 +58,13 @@ graph LR Visual representation -Within our [public board](https://github.com/orgs/aws-powertools/projects/7){target="_blank"}, you'll see the following values in the `Status` column: +Within our [public board](https://github.com/orgs/aws-powertools/projects/7/views/1?query=is%3Aopen+sort%3Aupdated-desc){target="_blank"}, you'll see the following values in the `Status` column: -* **Ideas**. Incoming and existing feature requests that are not being actively considered yet. These will be reviewed when bandwidth permits and based on demand. -* **Backlog**. Accepted feature requests or enhancements that we want to work on. -* **Working on it**. Features or enhancements we're currently either researching or implementing it. -* **Coming soon**. Any feature, enhancement, or bug fixes that have been merged and are coming in the next release. -* **Shipped**. Features or enhancements that are now available in the most recent release. -* **On hold**. Features or items that are currently blocked until further notice. -* **Pending review**. Features which implementation is mostly completed, but need review and some additional iterations. +- **Ideas**. Incoming and existing feature requests that are not being actively considered yet. These will be reviewed when bandwidth permits. +- **Backlog**. Accepted feature requests or enhancements that we want to work on. +- **Working on it**. Features or enhancements we're currently either researching or implementing it. +- **Coming soon**. Any feature, enhancement, or bug fixes that have been merged and are coming in the next release. +- **Shipped**. Features or enhancements that are now available in the most recent release. > Tasks or issues with empty `Status` will be categorized in upcoming review cycles. @@ -82,18 +86,18 @@ graph LR Our end-to-end mechanism follows four major steps: -* **Feature Request**. Ideas start with a [feature request](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type/feature-request%2Ctriage&template=feature_request.yml&title=Feature+request%3A+TITLE){target="_blank"} to outline their use case at a high level. For complex use cases, maintainers might ask for/write a RFC. - * Maintainers review requests based on [project tenets](index.md#tenets){target="_blank"}, customers reaction (πŸ‘), and use cases. -* **Request-for-comments (RFC)**. Design proposals use our [RFC issue template](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type/RFC%2Ctriage&template=rfc.yml&title=RFC%3A+TITLE){target="_blank"} to describe its implementation, challenges, developer experience, dependencies, and alternative solutions. - * This helps refine the initial idea with community feedback before a decision is made. -* **Decision**. After carefully reviewing and discussing them, maintainers make a final decision on whether to start implementation, defer or reject it, and update everyone with the next steps. -* **Implementation**. For approved features, maintainers give priority to the original authors for implementation unless it is a sensitive task that is best handled by maintainers. +- **Feature Request**. Ideas start with a [feature request](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2Ffeature-request%2Ctriage&projects=aws-powertools%2F7&template=feature_request.yml&title=Feature+request%3A+TITLE){target="_blank"} to outline their use case at a high level. For complex use cases, maintainers might ask for/write a RFC. + - Maintainers review requests based on [project tenets](index.md#tenets){target="_blank"}, customers reaction (πŸ‘), and use cases. +- **Request-for-comments (RFC)**. Design proposals use our [RFC issue template](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?assignees=&labels=type%2FRFC%2Ctriage&projects=aws-powertools%2F7&template=rfc.yml&title=RFC%3A+TITLE){target="_blank"} to describe its implementation, challenges, developer experience, dependencies, and alternative solutions. + - This helps refine the initial idea with community feedback before a decision is made. +- **Decision**. After carefully reviewing and discussing them, maintainers make a final decision on whether to start implementation, defer or reject it, and update everyone with the next steps. +- **Implementation**. For approved features, maintainers give priority to the original authors for implementation unless it is a sensitive task that is best handled by maintainers. -??? info "See [Maintainers](https://github.com/aws-powertools/powertools-lambda-typescript/blob/develop/MAINTAINERS.md) document to understand how we triage issues and pull requests, labels and governance." +??? info "See [Maintainers](./maintainers.md){target="_blank"} document to understand how we triage issues and pull requests, labels and governance." ## Disclaimer -The Powertools for AWS Lambda team values feedback and guidance from its community of users, although final decisions on inclusion into the project will be made by AWS. +The Powertools for AWS Lambda (TypeScript) team values feedback and guidance from its community of users, although final decisions on inclusion into the project will be made by AWS. We determine the high-level direction for our open roadmap based on customer feedback and popularity (πŸ‘πŸ½ and comments), security and operational impacts, and business value. Where features don’t meet our goals and longer-term strategy, we will communicate that clearly and openly as quickly as possible with an explanation of why the decision was made. diff --git a/docs/upgrade.md b/docs/upgrade.md new file mode 100644 index 0000000000..88a94294d5 --- /dev/null +++ b/docs/upgrade.md @@ -0,0 +1,7 @@ +--- +title: Upgrade guide +description: Guide to update between major Powertools for AWS Lambda (TypeScript) versions +--- + +!!! warning + This guide is a work in progress. We'll update it as we get closer to the 2.0 release. If you have any questions, or want to follow the progress, please join the discussion on the [GitHub issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1714). \ No newline at end of file diff --git a/layers/package.json b/layers/package.json index b118451c9b..95dab12127 100644 --- a/layers/package.json +++ b/layers/package.json @@ -9,6 +9,7 @@ "scripts": { "build": "echo 'Not applicable, run `npx cdk synth` instead to build the stack'", "test": "echo 'Not applicable'", + "jest": "jest --detectOpenHandles", "cdk": "cdk", "package": "echo 'Not applicable'", "lint": "eslint --ext .ts,.js --no-error-on-unmatched-pattern .", diff --git a/mkdocs.yml b/mkdocs.yml index 0fdc7b8484..7c49a95aab 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,18 +5,28 @@ repo_url: https://github.com/aws-powertools/powertools-lambda-typescript edit_uri: edit/main/docs nav: - - Homepage: index.md - - Changelog: changelog.md - - Roadmap: roadmap.md - - API reference: api/" target="_blank - - We Made This (Community): we_made_this.md - - Features: + - Homepage: + - index.md + - Changelog: changelog.md + - API reference: api/" target="_blank + - Upgrade guide: upgrade.md + - We Made This (Community): we_made_this.md + - Roadmap: roadmap.md + - Features: - core/tracer.md - core/logger.md - core/metrics.md - utilities/parameters.md - utilities/idempotency.md - utilities/batch.md + - Processes: + - Roadmap: roadmap.md + - Maintainers: maintainers.md + - Contributing: + - Development environment: contributing/setup.md + - Your first contribution: contributing/getting_started.md + - Conventions: contributing/conventions.md + - Testing: contributing/testing.md theme: name: material @@ -42,6 +52,7 @@ theme: - navigation.instant - navigation.indexes - navigation.tracking + - navigation.tabs - content.code.annotate - content.code.copy - announce.dismiss diff --git a/package.json b/package.json index 1292f6eb10..dab6966b98 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,9 @@ "scripts": { "init-environment": "husky install", "test": "npm t -ws", + "test:parallel": "lerna exec --no-bail --no-sort --stream --concurrency 8 -- npm run test", "test:e2e": "npm run test:e2e -ws", + "test:e2e:parallel": "lerna exec --no-bail --no-sort --stream --concurrency 8 -- npm run test:e2e", "commit": "commit", "setup-local": "npm ci && npm run build && npm run init-environment", "build": "npm run build -ws", @@ -75,4 +77,4 @@ "engines": { "node": ">=16" } -} +} \ No newline at end of file diff --git a/packages/batch/package.json b/packages/batch/package.json index 1ff802cdf4..e2c8701c2b 100644 --- a/packages/batch/package.json +++ b/packages/batch/package.json @@ -12,6 +12,7 @@ "scripts": { "test": "npm run test:unit", "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose", + "jest": "jest --detectOpenHandles --verbose", "test:e2e:nodejs16x": "echo 'Not Implemented'", "test:e2e:nodejs18x": "echo 'Not Implemented'", "test:e2e": "echo 'Not Implemented'", diff --git a/packages/commons/package.json b/packages/commons/package.json index a3e0e47296..9398f36a6a 100644 --- a/packages/commons/package.json +++ b/packages/commons/package.json @@ -12,6 +12,7 @@ "scripts": { "test": "npm run test:unit", "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose", + "jest": "jest --detectOpenHandles --verbose", "test:e2e": "echo 'Not Applicable'", "watch": "jest --watch", "generateVersionFile": "echo \"// this file is auto generated, do not modify\nexport const PT_VERSION = '$(jq -r '.version' package.json)';\" > src/version.ts", diff --git a/packages/idempotency/package.json b/packages/idempotency/package.json index 2f107526e7..aca801e6db 100644 --- a/packages/idempotency/package.json +++ b/packages/idempotency/package.json @@ -12,6 +12,7 @@ "scripts": { "test": "npm run test:unit", "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose", + "jest": "jest --detectOpenHandles --verbose", "test:e2e:nodejs16x": "RUNTIME=nodejs16x jest --group=e2e", "test:e2e:nodejs18x": "RUNTIME=nodejs18x jest --group=e2e", "test:e2e": "jest --group=e2e", diff --git a/packages/logger/package.json b/packages/logger/package.json index 62c72dae32..90afea2ead 100644 --- a/packages/logger/package.json +++ b/packages/logger/package.json @@ -12,6 +12,7 @@ "scripts": { "test": "npm run test:unit", "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose", + "jest": "jest --detectOpenHandles --verbose", "test:e2e:nodejs16x": "RUNTIME=nodejs16x jest --group=e2e", "test:e2e:nodejs18x": "RUNTIME=nodejs18x jest --group=e2e", "test:e2e": "jest --group=e2e", diff --git a/packages/metrics/package.json b/packages/metrics/package.json index 25fe12facc..5c1a384064 100644 --- a/packages/metrics/package.json +++ b/packages/metrics/package.json @@ -12,6 +12,7 @@ "scripts": { "test": "npm run test:unit", "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose", + "jest": "jest --detectOpenHandles --verbose", "test:e2e:nodejs16x": "RUNTIME=nodejs16x jest --group=e2e", "test:e2e:nodejs18x": "RUNTIME=nodejs18x jest --group=e2e", "test:e2e": "jest --group=e2e", diff --git a/packages/parameters/package.json b/packages/parameters/package.json index 9089020fca..5a6fa56f66 100644 --- a/packages/parameters/package.json +++ b/packages/parameters/package.json @@ -12,6 +12,7 @@ "scripts": { "test": "npm run test:unit", "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose", + "jest": "jest --detectOpenHandles --verbose", "test:e2e:nodejs16x": "RUNTIME=nodejs16x jest --group=e2e", "test:e2e:nodejs18x": "RUNTIME=nodejs18x jest --group=e2e", "test:e2e": "jest --group=e2e", diff --git a/packages/testing/package.json b/packages/testing/package.json index 7c28586b3a..c22980cb23 100644 --- a/packages/testing/package.json +++ b/packages/testing/package.json @@ -10,6 +10,7 @@ "scripts": { "test": "npm run test:unit", "test:unit": "jest --group=unit --detectOpenHandles --verbose", + "jest": "jest --detectOpenHandles --verbose", "test:e2e": "echo 'Not implemented'", "watch": "jest --watch", "build:cjs": "tsc --build --force && echo '{ \"type\": \"commonjs\" }' > lib/cjs/package.json", diff --git a/packages/tracer/package.json b/packages/tracer/package.json index db37da1d73..a3534a43bc 100644 --- a/packages/tracer/package.json +++ b/packages/tracer/package.json @@ -12,6 +12,7 @@ "scripts": { "test": "npm run test:unit", "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose", + "jest": "jest --detectOpenHandles --verbose", "test:e2e:nodejs16x": "RUNTIME=nodejs16x jest --group=e2e", "test:e2e:nodejs18x": "RUNTIME=nodejs18x jest --group=e2e", "test:e2e": "jest --group=e2e",