diff --git a/.github/scripts/post_release.js b/.github/scripts/post_release.js deleted file mode 100644 index 8c981fabc2..0000000000 --- a/.github/scripts/post_release.js +++ /dev/null @@ -1,94 +0,0 @@ -const LABEL_PENDING_RELEASE = 'pending-release'; -const LABEL_RELEASED = 'completed'; - -/** - * Fetch issues using GitHub REST API - * - * @param {object} gh_client - Pre-authenticated REST client (Octokit) - * @param {string} org - GitHub Organization - * @param {string} repository - GitHub repository - * @param {string} state - GitHub issue state (open, closed) - * @param {string} label - Comma-separated issue labels to fetch - * @return {Object[]} issues - Array of issues matching params - * @see {@link https://octokit.github.io/rest.js/v18#usage|Octokit client} - */ -const fetchIssues = async ({ - gh_client, - core, - org, - repository, - state = 'all', - label = LABEL_PENDING_RELEASE, -}) => { - try { - const { data: issues } = await gh_client.rest.issues.listForRepo({ - owner: org, - repo: repository, - state: state, - labels: label, - }); - - return issues.filter( - (issue) => Object.hasOwn(Object(issue), 'pull_request') === false - ); - } catch (error) { - core.setFailed(error); - throw new Error('Failed to fetch issues'); - } -}; - -/** - * Update labels on closed issues that are pending release - * - * Swaps the 'pending-release' label to 'completed' on each closed issue. - * GitHub natively links releases to issues, so no comment is needed. - * - * @param {object} gh_client - Pre-authenticated REST client (Octokit) - * @param {string} owner - GitHub Organization - * @param {string} repository - GitHub repository - * @see {@link https://octokit.github.io/rest.js/v18#usage|Octokit client} - */ -const updateLabels = async ({ gh_client, core, owner, repository }) => { - const issues = await fetchIssues({ - gh_client: gh_client, - org: owner, - repository: repository, - state: 'closed', - }); - - issues.forEach(async (issue) => { - core.info(`Updating labels for issue number ${issue.number}`); - - // Remove staged label; keep existing ones - const labels = issue.labels - .filter((label) => label.name !== LABEL_PENDING_RELEASE) - .map((label) => label.name); - - // Update labels including the released one - try { - await gh_client.rest.issues.setLabels({ - repo: repository, - owner, - issue_number: issue.number, - labels: [...labels, LABEL_RELEASED], - }); - } catch (error) { - core.setFailed(error); - throw new Error('Failed to label issue'); - } - - core.info(`Issue number ${issue.number} labeled`); - }); -}; - -// context: https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts -module.exports = async ({ github, context, core }) => { - core.info('Running post-release label update'); - - await updateLabels({ - gh_client: github, - core, - owner: context.repo.owner, - repository: context.repo.repo, - }); -}; diff --git a/.github/workflows/post-release.yml b/.github/workflows/post-release.yml deleted file mode 100644 index 12edd99d31..0000000000 --- a/.github/workflows/post-release.yml +++ /dev/null @@ -1,27 +0,0 @@ -name: Post Release - -on: - # Triggered manually - workflow_dispatch: {} - # Or triggered as result of a release - release: - types: [released] - -permissions: - contents: read - -jobs: - post_release: - permissions: - contents: read - issues: write - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Update labels on issues related to release - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - script: | - const post_release = require('.github/scripts/post_release.js') - await post_release({github, context, core}) diff --git a/.github/workflows/stale-issues.yml b/.github/workflows/stale-issues.yml deleted file mode 100644 index e3d9fa1d90..0000000000 --- a/.github/workflows/stale-issues.yml +++ /dev/null @@ -1,38 +0,0 @@ -name: "Close stale issues" - -on: - schedule: - - cron: "0 0 * * *" - -permissions: - contents: read - -jobs: - check-issues: - runs-on: ubuntu-latest - permissions: - issues: write - steps: - - uses: actions/stale@4391f3da665fdf50b6810c1a66712fb9ba21aa93 # v11.0.0 - with: - repo-token: ${{ secrets.GITHUB_TOKEN }} - stale-issue-message: "This issue has not received a response in 2 weeks. If you still think there is a problem, please leave a comment to avoid the issue from automatically closing." - close-issue-message: "Greetings! We are closing this issue because it has been open a long time and hasn’t been updated in a while and may not be getting the attention it deserves. We encourage you to check if this is still an issue in the latest release and if you find that this is still a problem, please feel free to comment or reopen the issue." - # Label applied or removed when an issue becomes stale - stale-issue-label: pending-close-response-required - remove-stale-when-updated: true - # Label and close type when a stale issue is finally closed - close-issue-label: rejected - close-issue-reason: not_planned - # Exempt any issue that hasn't been triaged yet, or that is clearly labeled - exempt-issue-labels: triage,confirmed,blocked,on-hold,completed - # Include only issues that were labeled as `need-response` (aka only issues that need a response from the customer) - only-issue-labels: need-response - # Settings specific to issues - days-before-issue-stale: 14 - days-before-issue-close: 7 - # Set to ignore PRs - days-before-pr-stale: -1 - days-before-pr-close: -1 - # Operations - operations-per-run: 60 diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md index d9180f1fd5..395984a59e 100644 --- a/CODING_STANDARDS.md +++ b/CODING_STANDARDS.md @@ -4,7 +4,8 @@ Reference for writing code and tests in this repo. Rules are grouped by concern; ## Project layout and imports -- The codebase is TypeScript, ESM. Each utility lives in `packages/` with `src` for source and `test` for tests. +- The codebase is TypeScript, ESM. Each utility lives in `packages/` with `src` for source and `tests` for tests, split into `tests/unit` and `tests/e2e`. +- Not every workspace is a published package: `examples/snippets`, `examples/app`, `layers`, and `packages/testing` share dependencies and tooling with the rest of the monorepo but never ship to npm. - Import across packages by package name (`import { myFunction } from '@aws-lambda-powertools/commons'`), with the dependency declared in the importing package's `package.json`. Relative paths stay within a package and always carry the `.js` extension (`from './utils.js'`). - Utilities and types shared by two or more packages belong in `@aws-lambda-powertools/commons`. - Sibling-package dependencies (including peerDependencies) are exact pins matching the current lockstep version (`"@aws-lambda-powertools/commons": "2.35.0"`), no range specifiers. @@ -54,7 +55,7 @@ Run from the repo root with `-w `, or from the package directory: ## Unit tests -Tests use `vitest` and live in each package's `test` directory. Run with `npm run test:unit -w packages/` (or `npm run test:unit` from the package directory). Write unit tests only — end-to-end tests happen when the user asks for them. +Tests use `vitest` and live in each package's `tests/unit` directory. Run with `npm run test:unit -w packages/` (or `npm run test:unit` from the package directory). Write unit tests only — end-to-end tests happen when the user asks for them. Coverage: CI enforces 100% coverage on `src/**` (types files excluded) via `npm run test:unit:coverage` — the plain test run skips coverage, so verify with the `:coverage` variant before finishing. Every new source line needs a covering test. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e8858e695..db837d1e15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,38 +2,62 @@ ## Table of contents -- [Reporting Bugs/Feature Requests](#reporting-bugsfeature-requests) -- [Contributing via Pull Requests](#contributing-via-pull-requests) +- [Reporting bugs and requesting features](#reporting-bugs-and-requesting-features) + - [What we look for when reviewing an RFC](#what-we-look-for-when-reviewing-an-rfc) +- [Finding contributions to work on](#finding-contributions-to-work-on) +- [Contributing via pull requests](#contributing-via-pull-requests) - [Dev setup](#dev-setup) + - [Coding standards](#coding-standards) - [Sending a pull request](#sending-a-pull-request) + - [End-to-end tests](#end-to-end-tests) - [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) - -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. - +Thank you for your interest in contributing to our project. Whether it's a bug report, a new feature, a correction, or additional documentation, we greatly value feedback and contributions from our community. We encourage contributions from the community and we will work with contributors to merge their pull requests. -Rarely, we may close pull requests that do not meet our guidelines specified in CONTRIBUTING.md, or will require unreasonable effort to meet our quality bar. +Rarely, we may close pull requests that do not meet the guidelines in this document, or will require unreasonable effort to meet our quality bar. 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 +## Reporting bugs and requesting features + +Before opening anything new, please check [existing open](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) +and [recently closed](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed) issues, so nobody duplicates work. +Then pick the entry point that matches what you have: + +- [Bug report](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?template=bug_report.yml) — a runtime error you can reproduce, whether or not you know how to fix it. +- [Feature request](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?template=feature_request.yml) — a new feature or enhancement that would help you, your team, or other customers. +- [Documentation improvement](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?template=documentation_improvements.yml) — typos, unclear guides, missing examples, diagrams. +- [Maintenance](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?template=maintenance.yml) — technical debt, governance, and anything internal. +- [Design proposal (RFC)](https://github.com/aws-powertools/powertools-lambda-typescript/discussions/new?category=rfcs-request-for-comments) — a Request for Comments that explores the user experience and tradeoffs of a larger change before anyone writes code. Substantial feature requests usually start life here. +- [Share your work](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?template=share_your_work.yml) — blog posts, workshops, talks, and sample apps built with Powertools for AWS Lambda. +- [Become a public reference](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new?template=support_powertools.yml) — tell everyone how your organization uses Powertools for AWS Lambda. +- [GitHub Discussions](https://github.com/aws-powertools/powertools-lambda-typescript/discussions) — questions, half-formed ideas, and anything that isn't an issue yet. + +### What we look for when reviewing an RFC + +RFC review is collaborative. Before submitting an RFC, use the [RFC template](https://github.com/aws-powertools/powertools-lambda-typescript/discussions/new?category=rfcs-request-for-comments) and make sure the proposal: + +- Aligns with our [tenets](https://docs.aws.amazon.com/powertools/typescript/latest/#tenets). +- Defines the use case and recommended usage, including Lambda-specific constraints and how the design works across the relevant utilities. +- Explains the mechanics at a level that someone familiar with the codebase could implement, without prescribing fine-grained implementation details. +- Covers alternatives, including existing projects or whether the use case belongs in a separate project. +- Accounts for the ongoing maintenance and skills the proposal would require. +- Says whether you want to help implement it and where you need guidance. + +## Finding contributions to work on -We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements. +Browsing the [open issues](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) is the best place to start. +Issues still labelled for triage are being scoped, so comment before picking one up. +[GitHub Discussions](https://github.com/aws-powertools/powertools-lambda-typescript/discussions) is where questions and design proposals get debated — answering a question there is as valuable as a code change. - -[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. - +Documentation is always open: look for places that could use a clearer example or a diagram, and keep in mind a diverse audience that often reads English as a second language. -## Contributing via Pull Requests +## Contributing via pull requests Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: @@ -46,51 +70,88 @@ At a high level, these are the steps to get code merged in the repository - don' ```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) + Project setup
(npm run setup-local) : Code checkout + : Dependencies + : Git hooks + : Local branch + : Local changes + : Local tests + + Pre-commit checks
(git commit) : Code linting and formatting : Markdown linting - 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 - : Static analysis (CodeQL) + Pre-push checks
(git push) : Type check tests + : Unit tests with 100% coverage + + Pull Request
(CI checks) : Conventional Commits title drives labels and changelog + : Linked issue (closes #issue_number) + : Acknowledgment retained from the PR template + : Linting and unit tests on every supported Node.js version + : 100% coverage of each package's src directory + : No new CodeQL alerts + : No known-vulnerable dependencies + : Third-party GitHub Actions pinned to a commit SHA : 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 + After merge
(CI checks) : Deploy staging docs : Update draft release ``` +The checks are defined in the [lint and unit test](.github/workflows/pr-run-linting-check-and-unit-tests.yml), [CodeQL](.github/workflows/codeql.yml), [dependency review](.github/workflows/dependency-review.yml), and [workflow security](.github/workflows/secure-workflows.yml) workflows. +A maintainer may add a `do-not-merge` label, which blocks the merge until the underlying issue is resolved. + ### Dev setup -Firstly, [fork the repository](https://github.com/aws-powertools/powertools-lambda-typescript/fork), then use `npm run setup-local` on your local machine to install all dependencies and setup pre-commit hooks. +[Fork the repository](https://github.com/aws-powertools/powertools-lambda-typescript/fork), clone your fork, then run `npm run setup-local` from the repo root to install dependencies, build every workspace, and install the Git hooks. New to this? GitHub documents [how to fork and clone a project](https://docs.github.com/en/get-started/quickstart/contributing-to-projects). -### Sending a pull request +Prerequisites: + +- **Node.js 24.x**, the version pinned in `.nvmrc`, so `nvm use` or `fnm use` picks it up. npm 11.x ships with it; this is an npm workspaces monorepo, so always install from the repo root rather than from a package directory. +- **Docker**, only to preview the documentation with `npm run docs:docker:*`. Nothing else in the repo needs it. +- **Python 3**, only to preview the documentation without Docker, with `npm run docs:local:*`. +- **An AWS account and the AWS CLI**, only to run [end-to-end tests](#end-to-end-tests). + +### Coding standards -To send us a pull request, please follow these steps: +[`CODING_STANDARDS.md`](CODING_STANDARDS.md) is the source of truth for package layout, TypeScript style, JSDoc, unit tests, and the commands that verify all of them. Read it before writing code, tests, or documentation. If you drive a coding agent, point it at [`AGENTS.md`](AGENTS.md). -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. +### Sending a pull request + +1. Create a branch named after the change you are contributing, e.g. `improv/logger-debug-sampling`. +2. Commit to your fork using clear commit messages. Don't worry about the commit format — we squash every pull request on merge. +3. Run the Git hooks; they are mandatory. + Never bypass them with `--no-verify`, `HUSKY=0`, or similar; if a hook fails, fix the cause. + If hooks do not run in your environment, including Git worktrees and some CI or agent sandboxes, manually run `npx lint-staged`, `npm run build:tests -ws --if-present`, and `npx vitest --run --exclude tests/unit/layer-publisher.test.ts --coverage --coverage.thresholds.100 tests/unit` before pushing. +4. Open a pull request with a title that follows the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/), and fill in every area the pull request template asks for — including the issue it closes. 5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. -GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and -[creating a pull request](https://help.github.com/articles/creating-a-pull-request/). +First pull request ever? GitHub documents [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/). + +### End-to-end tests + +End-to-end tests give us confidence that a Lambda function using our code behaves as expected once deployed — event source configuration, IAM permissions, and all. They deploy real resources with AWS CDK, invoke the functions, assert on the logs, metrics, and traces they emit, then tear everything down. + +> [!WARNING] +> Running end-to-end tests creates AWS resources in your account, which may incur costs. Some services are covered by the [AWS Free Tier](https://aws.amazon.com/free/), but not all of them. Use a dedicated AWS account, and when in doubt let the CI on our repository run them for you. + +You'll need an [AWS account bootstrapped with CDK](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) and the [AWS CLI installed and configured](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). Then, from the repo root: + +- `npm run test:e2e -w packages/metrics` runs the end-to-end suites of a single package on the default Node.js runtime. +- `npm run test:e2e:nodejs24x -w packages/metrics` runs the same suites pinned to a specific runtime. + +```mermaid +sequenceDiagram + Dev Environment / CI->>+Vitest: npm run test:e2e + Vitest-->Vitest: Synthetize CloudFormation Stack + Vitest->>+AWS: Deploy Stack + Vitest->>+AWS: Invoke Lambda function + AWS->>Vitest: Report logs / results + Vitest-->Vitest: Assert logs/result + Vitest->>+AWS: Destroy Stack + Vitest->>+Dev Environment / CI: show test results +``` + +In CI these only run when a maintainer triggers [`run-e2e-tests.yml`](.github/workflows/run-e2e-tests.yml), which fans the suites out across every supported runtime version and architecture. ### Local documentation @@ -126,37 +187,6 @@ If you have Python 3.x installed, you can run the documentation website and API npm run docs:local:run ``` -## Conventions - -### General terminology and practices - -| 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 [Biome](http://biomejs.dev) to enforce style and format 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.aws.amazon.com/powertools/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. | - -### 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) | - -**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. - -## Finding contributions to work on - -Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use 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). - ## Code of Conduct This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 4263851370..9667806b6d 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,4 +1,286 @@ - +# Maintainers playbook -> [!IMPORTANT] -> Maintainers' playbook moved: +This is the operational runbook for maintainers of Powertools for AWS Lambda (TypeScript): who the maintainers are, the labels we use, and the step-by-step processes we follow to triage, release, and operate the project. + +If you're looking to contribute, read [CONTRIBUTING.md](./CONTRIBUTING.md) instead. + +> Security reports come before features and bugs. This repository is monitored and supported 24/7 by Amazon Security — see [SECURITY.md](./SECURITY.md) for how vulnerabilities are reported and handled. + +## Current maintainers + +| Maintainer | GitHub ID | Affiliation | +| -------------- | ------------------------------------------- | ----------- | +| Andrea Amorosi | [dreamorosi](https://github.com/dreamorosi) | Amazon | +| Swopnil Dangol | [sdangol](https://github.com/sdangol) | Amazon | +| Stefano Vozza | [svozza](https://github.com/svozza) | Amazon | + +## Emeritus maintainers + +Previous active maintainers who contributed to this project. + +| Maintainer | GitHub ID | Affiliation | +| -------------------------- | ----------------------------------------------- | ----------- | +| Alexander Schueren | [am29d](https://github.com/am29d) | OpenAI | +| Simon Thulbourn | [sthulb](https://github.com/sthulb) | | +| Sara Gerion | [saragerion](https://github.com/saragerion) | Amazon | +| Florian Chazal | [flochaz](https://github.com/flochaz) | | +| Chadchapol Vittavutkarnvej | [ijemmy](https://github.com/ijemmy) | Booking.com | +| Alan Churley | [alan-churley](https://github.com/alan-churley) | CloudCall | +| Michael Bahr | [bahrmichael](https://github.com/bahrmichael) | Stedi | + +## Labels + +Labels we actually use, and what applies them. Anything marked _manual_ is only ever set by a maintainer, so don't assume it's there. + +### Issue lifecycle + +| Label | Usage | Applied by | +| --------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------- | +| `triage` | Not yet triaged; remove it once you've validated the request or repro | Issue templates | +| `researching` | Still being discussed or refined; we'll update once we know more | Manual | +| `need-more-information` | Missing information before we can make a call | Manual | +| `need-customer-feedback` | Needs more customer input before deciding or revisiting a decision | Manual | +| `need-response` | Waiting on the author; opts the issue into org-level stale automation | Manual | +| `pending-close-response-required` | Went stale waiting for a response and will be closed unless it moves | Organization-level automation | +| `blocked` | Progress is blocked by an external dependency or reason | Manual | +| `on-hold` | Parked and will be revisited in the future | Manual | +| `next-major-version` | Deferred to the next major version | Manual | +| `pending-release` | Merged and shipping in the next release | Organization-level automation, when the PR merges | + +### Type and area + +Issue type — bug, feature, documentation, or maintenance — is tracked with [GitHub Issue Types](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/configuring-issue-types) rather than labels. What's left are the labels that qualify an item further. + +| Label | Usage | Applied by | +| -------------------- | ------------------------------------------------------ | --------------------------------------- | +| `bug-upstream` | Bug caused by an upstream dependency | Manual | +| `good-first-issue` | Suitable for someone who wants to start contributing | Manual | +| `help-wanted` | We'd appreciate support from the community on this one | Manual | +| `customer-reference` | Authorization to use a customer name publicly | `support_powertools.yml` issue template | +| `community-content` | Community content to feature in the documentation | `share_your_work.yml` issue template | + +Area labels flag which part of the library an item belongs to: `logger`, `metrics`, `tracer`, `parameters`, `idempotency`, `batch`, `parser`, `validation`, `jmespath`, `event-handler`, `data-masking`, `kafka`, `signer`, `commons`, `layers`, and `automation` for CI/CD and workflows. + +### Pull requests + +| Label | Usage | Applied by | +| -------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------ | +| `do-not-merge` | Blocks the merge; `.github/workflows/on_pr_updates.yml` fails while it's set | Manual | +| `need-issue` | PR is missing a related issue | Organization-level PR checks | +| `dependencies` | Touches dependencies | Dependabot, alongside an ecosystem label | +| `javascript`, `github_actions`, `docker`, `python` | Ecosystem a Dependabot PR updates | Dependabot | +| `skip-changelog` | Excluded from the drafted release notes, see `.github/release-drafter.yml` | Automation, on the version bump and layer ARN docs PRs | +| `size/XS` … `size/XXL` | Rough PR size, from 0-9 LOC up to 1K+ LOC | Organization-level automation | + +## Triaging issues and pull requests + +Remove `triage` once you can confirm a request is valid or a bug reproduces, then set a state label from the table above if one applies — an item with no state label is one whose scope is clear and that nothing is blocking. Give priority to the original author for implementation, unless the task is sensitive enough that it's better handled by maintainers. + +Not everything needs a label: close an issue as **duplicate** when it repeats an existing one, and as **not planned** when we won't work on it. The close reason is what customers see, and it keeps the label list to what's actionable. + +Issues are tracked on the [board of activities](https://github.com/orgs/aws-powertools/projects/7). + +### What counts as a bug + +A bug produces incorrect or unexpected results at runtime that differ from the intended behavior, is reproducible, and affects customers who follow the recommended usage. Documentation snippets, use of internal components, and unadvertised functionality are not bugs — close the issue as not planned and explain why. + +For bugs caused by an upstream dependency, apply `bug-upstream` and ask the author whether they'd like to raise the issue upstream or prefer us to. Assess the impact and decide whether an emergency release is warranted; ask another maintainer when in doubt. + +### Reviewing pull requests + +PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/) — they feed the [changelog](./CHANGELOG.md) and the drafted release notes, so make sure they read well to a human. PR titles, related issues, and the acknowledgment checkbox are enforced by organization-level checks, not by workflows in this repository. + +Labels need no action when you merge: organization-level automation applies `pending-release` when the PR merges and removes it automatically when the release ships. + +## Adding a new package + +Two things need to happen before a brand-new package (e.g. a new utility) can ship: its name has to exist on npm, and CI has to know about it. + +### Reserving the package name on npm + +`Make Release` publishes with [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers) via GitHub Actions OIDC, so we get provenance without storing a long-lived `NPM_TOKEN`. + +Trusted publishers can only be configured for a package that **already exists** on npm, so a new package can't reserve its own name that way the first time around: a maintainer has to publish a placeholder version manually, once, before the first real release. + +1. **Create a temporary local package** using the same placeholder shape every utility has used before its first release: + + ```json + { + "name": "@aws-lambda-powertools/", + "version": "0.0.0", + "description": "The package for the Powertools for AWS Lambda (TypeScript) library", + "author": { "name": "Amazon Web Services", "url": "https://aws.amazon.com" }, + "publishConfig": { "access": "public" }, + "homepage": "https://github.com/aws-powertools/powertools-lambda-typescript", + "license": "MIT-0", + "main": "./lib/index.js", + "types": "./lib/index.d.ts", + "files": ["lib"], + "repository": { + "type": "git", + "url": "git+https://github.com/aws-powertools/powertools-lambda-typescript.git" + }, + "bugs": { "url": "https://github.com/aws-powertools/powertools-lambda-typescript/issues" }, + "dependencies": {}, + "keywords": ["aws", "lambda", "powertools", "handler", "nodejs", "serverless"], + "devDependencies": {} + } + ``` + + Add a `README.md` with the same "do not use this in production yet" disclaimer other placeholders use — [`@aws-lambda-powertools/validation@0.0.0`](https://www.npmjs.com/package/@aws-lambda-powertools/validation/v/0.0.0) is a good reference — and a `lib/index.js`/`lib/index.d.ts` pair where the former only logs that it's a placeholder reserving the name. + +2. **Authenticate locally** as an npm user who's a member of the `@aws-lambda-powertools` org with publish rights. Use a short-lived, least-privilege token, never commit it to `.npmrc`, and revoke it as soon as you're done. + +3. **Publish with the `pre` dist-tag**, not `latest`: + + ```bash + npm publish --access public --tag pre + ``` + + npm always assigns `latest` to the very first version ever published for a package, regardless of `--tag`, so `0.0.0` will briefly carry both `latest` and `pre`. That's expected and self-corrects: the next real release moves `latest` forward, while `pre` stays pinned to `0.0.0` as a permanent marker of the placeholder. + +4. **Configure Trusted Publishing** at `https://www.npmjs.com/package//access`: add a Trusted Publisher for GitHub Actions pointing at this repository and the `make-release.yml` workflow. This is what lets `Make Release` publish real versions with OIDC and provenance, without an `NPM_TOKEN`. + +### Wiring the package into CI + +The PR that adds the package must also add it to: + +- the `workspaces` array in the root `package.json` — this is also what gets it into the Lambda layer, since the layer bundles every non-private `@aws-lambda-powertools/*` workspace; +- `.github/workflows/reusable-run-linting-check-and-unit-tests.yml`; +- `.github/workflows/quality_check.yml`; +- `.github/workflows/run-e2e-tests.yml`, if it has end-to-end tests. + +Once that's done, the package ships like any other on the next `Make Release` run. + +## Releasing a new version + +It usually takes under an hour end to end, most of it spent waiting on the layer rollout and on the two PRs that need a human review. + +1. **Run the end-to-end tests** via the `Run e2e Tests` workflow and make sure they pass. +2. **Run `Make Version`** (`.github/workflows/make-version.yml`) and pick a release type — `auto` unless you have a reason not to. It bumps every package version, regenerates the changelogs, updates the user agent version in `packages/commons/src/version.ts`, and opens a `chore(ci): bump version to X.Y.Z` PR. +3. **Review and merge the version PR.** Read the diff carefully: the version numbers and the changelog are what customers will see. `.github/workflows/on_version_bump_pr_merge.yml` watches for that merge and dispatches `Make Release` for you. +4. **Approve the `Release` deployment** when `Make Release` asks for it — that's the gate in front of publishing to npm. +5. **Let `Make Release` run.** In order, it: + - runs linting and unit tests; + - publishes every workspace to npm with provenance, then waits until the registry actually serves the new versions; + - creates and pushes the `vX.Y.Z` tag; + - builds the layer and rolls it out to Beta and then Prod across commercial Regions, with a canary in each; + - writes the Prod SSM parameters; + - copies the layer into the GovCloud and China partitions, Gamma then Prod, both in parallel; + - opens a `chore(ci): update layer ARN on documentation` PR once all three Prod deployments are done. +6. **Review and merge the layer ARN docs PR.** `.github/workflows/on_layer_docs_pr_merge.yml` picks up the merge and dispatches `Rebuild latest docs`, which republishes the user guide and API reference. +7. **Draft and publish the release notes** (see below). Organization-level automation removes `pending-release` from shipped issues once the release is published. + +### Release process visualized + +The GitHub Actions UI is the source of truth; this is a close visual representation of the main steps, with approximate durations. + +```mermaid +gantt + +title Release process +dateFormat HH:mm +axisFormat %H:%M + +Release start : milestone, m1, 10:00, 8s + +section Version + Bump versions and changelogs : active, 8s + Open version PR : active, 8s + +Review and merge version PR : milestone, m2 + +section QA + Linting and unit tests : active, 2.4m + +section npm + Publish workspaces (provenance) : active, npm, 10:03, 40s + Verify registry propagation : active, after npm, 30s + +npmjs.com release : milestone, m3 + +section Git release + Create and push tag : active, 8s + +section Layer release + Build layer : active, layer_build, 10:05, 2.5m + Deploy Beta (incl. canary) : active, layer_beta, after layer_build, 6m + Deploy Prod (incl. canary) : active, layer_prod, after layer_beta, 6m + +Layer release : milestone, m4 + +section SSM + Update SSM parameters (Prod) : active, after layer_prod, 2m + +section GovCloud + Publish GovCloud layers (Gamma) : active, govcloud_gamma, after layer_prod, 8s + Publish GovCloud layers (Prod) : active, govcloud_prod, after govcloud_gamma, 8s +GovCloud layers published : milestone, m5 + +section China + Publish China layers (Gamma) : active, china_gamma, after layer_prod, 8s + Publish China layers (Prod) : active, china_prod, after china_gamma, 8s +China layers published : milestone, m6 + +section Docs + Commit layer ARNs : active, after govcloud_prod china_prod, 8s + Open docs PR : active, 8s + +Review and merge docs PR : milestone, m7 + + Publish updated docs : active, 2m + +Documentation release : milestone, m8 + +Release complete : milestone, m9 +``` + +### Drafting release notes + +`.github/workflows/release-drafter.yml` keeps a draft release ready on the [Releases page](https://github.com/aws-powertools/powertools-lambda-typescript/releases) — open it with the edit pencil. + +Check that the `tag` field is the version you're releasing, the target branch is `main`, and the release title matches the tag, e.g. `v2.28.0`. Changes are grouped by label according to the `categories` in `.github/release-drafter.yml`. + +**I spotted a typo or incorrect grouping — how do I fix it?** Edit the PR title and labels, then re-run the [Release Drafter workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/release-drafter.yml) to regenerate the draft. + +This won't change the changelog, since the merge commit is immutable — that's fine. We'd only ever rewrite git history if it could genuinely confuse customers, and we'd pair with another maintainer to do it. + +Then replace the `[Human readable summary of changes]` placeholder with what you want customers to take away from this release. Questions worth asking yourself: + +- Can customers understand at a high level what changed? +- Is there a link to the documentation for each main change? +- Would a graphic or code snippet make it easier to read? +- Is there a key contributor worth calling out? Everyone is credited automatically, so use this for exceptional cases. If someone is missing from the generated list, add them manually. + +Once you're happy, hit `Publish release`. + +## Running end-to-end tests + +End-to-end tests must pass before a release. Run them via the [Run e2e Tests workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/run-e2e-tests.yml). Also run them manually for large maintainer-authored contributions before merging to `main`. + +To run them locally you need the [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) and a [bootstrapped account](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html). With a default AWS CLI profile configured, or `AWS_PROFILE` set: + +```bash +npm run test:e2e # every package, sequentially +npm run test:e2e -w packages/logger # a single package +``` + +These tests deploy real infrastructure. `.github/workflows/sweep-stale-e2e-stacks.yml` sweeps up anything a failed run leaves behind, but prefer cleaning up after yourself. + +## Releasing a documentation hotfix + +You can republish the documentation without a full release via the [Rebuild latest docs workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/rebuild_latest_docs.yml). Choose `Run workflow`, keep `main` as the branch, and pass the latest published version. This updates both the user guide and the API reference. + +## Publishing Lambda Layers to a new AWS Region + +When a new AWS Region becomes available, check that it supports AWS Lambda and the Node.js runtimes we publish for, then: + +1. Run the `Region Bootstrap` workflow (`.github/workflows/bootstrap_region.yml`) once for `beta` and once for `prod`, passing the new Region. It bootstraps CDK in that Region, then runs the `layer-balancer` `balance` command to copy every existing layer version from `us-east-1`, so the new Region ends up with the same layer version numbers as everywhere else. +2. Add the Region to the `region` matrix in `.github/workflows/reusable_deploy_layer_stack.yml` and to the `region` matrix in `.github/workflows/update_ssm.yml`, so future releases deploy the layer and publish SSM parameters there. +3. Add a row for the Region to the ARN table in `docs/getting-started/lambda-layers.md`, using the layer version currently published. From then on `.github/scripts/update_layer_arn.sh` keeps it current on every release. + +If an existing Region drifts behind — a failed deployment, for instance — run `Region Balance` (`.github/workflows/layer_balance.yml`) to copy the missing versions across, optionally passing `start_at` to resume from a specific layer version. + +Regions temporarily excluded from releases are commented out in the deploy matrices and listed in `paused_regions` in `.github/scripts/update_layer_arn.sh`, so their frozen ARNs aren't bumped in the docs. Keep the two in sync. + +To re-deploy a partition outside the normal release flow, run `Layer Deployment (Partitions)` (`.github/workflows/layers_partitions.yml`) with the target partition. diff --git a/README.md b/README.md index 5b4333f255..bd3e269166 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ You can use the library in both TypeScript and JavaScript code bases. > Also available in [Python](https://github.com/aws-powertools/powertools-lambda-python), [Java](https://github.com/aws-powertools/powertools-lambda-java), and [.NET](https://github.com/aws-powertools/powertools-lambda-dotnet). -**[Documentation](https://docs.aws.amazon.com/powertools/typescript/latest)** | **[npmjs.com](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://docs.aws.amazon.com/powertools/typescript/latest/roadmap)** | **[Examples](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples)** +**[Documentation](https://docs.aws.amazon.com/powertools/typescript/latest)** | **[npmjs.com](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Examples](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples)** ## Features @@ -45,7 +45,7 @@ You can use Powertools for AWS Lambda (TypeScript) by installing it with your fa - **Idempotency**: `npm install @aws-lambda-powertools/idempotency @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb` see [documentation](https://docs.aws.amazon.com/powertools/typescript/latest/features/idempotency/#installation) for other providers - **Batch Processing**: `npm install @aws-lambda-powertools/batch` - **JMESPath Functions**: `npm install @aws-lambda-powertools/jmespath` -- **Parser**: `npm install @aws-lambda-powertools/parser zod@~3` +- **Parser**: `npm install @aws-lambda-powertools/parser zod` - **Validation**: `npm install @aws-lambda-powertools/validation` - **Kafka**: `npm install @aws-lambda-powertools/kafka` see [documentation](https://docs.aws.amazon.com/powertools/typescript/latest/features/kafka/#installation) for Avro and Protobuf support - **Data Masking**: `npm install @aws-lambda-powertools/data-masking @aws-crypto/client-node` diff --git a/docs/contributing/conventions.md b/docs/contributing/conventions.md deleted file mode 100644 index 9ee3649c54..0000000000 --- a/docs/contributing/conventions.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -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 [Biome](http://biomejs.dev){target="_blank"} for linting and formatting 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.aws.amazon.com/powertools/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: - -* `examples/snippets`: contains the documentation code snippets -* `examples/app`: contains an example project that can be deployed via AWS CDK or AWS SAM -* `layers`: contains the code used to build and publish the [Lambda layers](../getting-started/lambda-layers.md) - -## 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) | diff --git a/docs/contributing/getting_started.md b/docs/contributing/getting_started.md deleted file mode 100644 index f45565c75f..0000000000 --- a/docs/contributing/getting_started.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -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 GitHub Discussions. - -| Type | Description | -| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Documentation](https://s12d.com/pt-ts-new-issue-documentation){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://s12d.com/pt-ts-new-issue-feature-request){target="_blank" rel="nofollow"} | New features 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://s12d.com/pt-ts-new-rfc){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://s12d.com/pt-ts-new-issue-bug){target="_blank" rel="nofollow"} | A runtime error that is reproducible whether you have an idea how to solve it or not | -| [Advocacy](https://s12d.com/pt-ts-new-issue-community-content){target="_blank" rel="nofollow"} | Share what you did with Powertools for AWS Lambda. Blog posts, workshops, presentation, sample applications, podcasts, etc. | -| [Public reference](https://s12d.com/pt-ts-new-issue-public-reference){target="_blank" rel="nofollow"} | Become a public reference to share how you're using Powertools for AWS Lambda at your organization | -| [Discussions](https://github.com/aws-powertools/powertools-lambda-typescript/discussions){target="_blank" rel="nofollow"} | Kick off a discussion on GitHub, introduce yourself, and help respond to existing questions from the community | -| [Maintenance](https://s12d.com/pt-ts-new-issue-bug-maintenance){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://s12d.com/pt-ts-help-wanted){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://s12d.com/pt-ts-need-customer-feedback){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://s12d.com/pt-ts-open-rfcs){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://s12d.com/pt-ts-backlog){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.aws.amazon.com/powertools/typescript/latest/){target="_blank"} | Documentation can always be improved. Look for areas that could use a better example, or a diagram - keep in mind a diverse audience and English as a second language folks | -| [Participate in discussions](https://github.com/aws-powertools/powertools-lambda-typescript/discussions){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 [GitHub Discussions](https://github.com/aws-powertools/powertools-lambda-typescript/discussions){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 the proposed changes under [an existing issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aopen+is%3Aupdated-desc) or a new one 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 title that follows the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/); the title check's failure comment lists the allowed types and scopes. -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. diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md deleted file mode 100644 index 2e9f6a70f7..0000000000 --- a/docs/contributing/setup.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Development environment -description: Setting up your development environment for contribution ---- - - - -[![GitHub Discussions](https://img.shields.io/badge/GitHub-Discussions-181717.svg?logo=github)](https://github.com/aws-powertools/powertools-lambda-typescript/discussions){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"}. - -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 24.x](https://nodejs.org/download/release/latest-v24.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 10.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) - -## Local environment - -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: - -#### Using Docker (recommended) - -1. Build the Docker image (only needed the first time): - - ```bash - npm run docs:docker:build - ``` - -2. Run the documentation website: - - ```bash - npm run docs:docker:run - ``` - -#### Using Python directly - -If you have Python installed, you can run the documentation website and API reference locally without Docker: - -1. Create a virtual environment and install dependencies: - - ```bash - npm run docs:local:setup - ``` - -2. Run the documentation website: - - ```bash - npm run docs:local:run - ``` diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md deleted file mode 100644 index ab833fd3e4..0000000000 --- a/docs/contributing/testing.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -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 use [Vitest](http://vitest.dev) as test runner and are grouped by packages and type. You can run each group separately or all together by passing extra arguments to the test command. - -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 - -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/) 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:nodejs24x -w packages/metrics` to run all the integration tests for the `metrics` module using the `nodejs24x` 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->>+Vitest: npm run test:e2e - Vitest-->Vitest: Synthetize CloudFormation Stack - Vitest->>+AWS: Deploy Stack - Vitest->>+AWS: Invoke Lambda function - AWS->>Vitest: Report logs / results - Vitest-->Vitest: Assert logs/result - Vitest->>+AWS: Destroy Stack - Vitest->>+Dev Environment / CI: show test results -``` diff --git a/docs/maintainers.md b/docs/maintainers.md deleted file mode 100644 index 5232b23afa..0000000000 --- a/docs/maintainers.md +++ /dev/null @@ -1,442 +0,0 @@ ---- -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 | -| Swopnil Dangol | [sdangol](https://github.com/sdangol){target="_blank" rel="nofollow"} | Amazon | -| Stefano Vozza | [svozza](https://github.com/svozza){target="_blank" rel="nofollow"} | Amazon | - -## Emeritus - -Previous active maintainers who contributed to this project. - -| Maintainer | GitHub ID | Affiliation | -| -------------------------- | ------------------------------------------------------------------------------- | ----------- | -| Alexander Schueren | [am29d](https://github.com/am29d){target="_blank" rel="nofollow"} | | -| Simon Thulbourn | [sthulb](https://github.com/sthulb){target="_blank" rel="nofollow"} | Amazon | -| 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 | -| documentation | Improvements or additions to documentation | Examples/Readme files; Doc additions, fixes, etc.; | -| logger | Items related to the Logger Utility | PR automation | -| metrics | Items related to the Metrics Utility | PR automation | -| tracer | Items related to the Tracer Utility | PR automation | -| idempotency | Items related to the Idempotency Utility | PR automation | -| parameters | Items related to the Parameters Utility | PR automation | -| commons | Items related to the Commons Utility | PR automation | -| jmespath | Items related to the JMESPath Utility | PR automation | -| validation | Items related to the Validation Utility | PR automation | -| batch | Items related to the Batch Processing Utility | PR automation | -| parser | Items related to the Parser Utility | PR automation | -| event-handler | Items related to the Event Handler Utility | PR automation | -| automation | Items related to automation like GitHub workflows or CI/CD | PR automation | -| 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 | -| bug | Unexpected, reproducible and unintended software behavior | PR/Release automation; Doc snippets are excluded; | -| bug-upstream | Bug caused by upstream dependency | | -| not-a-bug | New and existing bug reports incorrectly submitted as bug | Analytics | -| deprecation | This item contains code deprecation | | -| duplicate | This issue is a duplicate of an existing one | Analytics | -| feature-request | Issue requesting new or enhancements to existing features | Issue template | -| feature | PRs that introduce new features | PR automation | -| enhancement | PRs that introduce minor changes, usually to existing features | PR automation | -| RFC | Technical design documents related to a feature request | | -| internal | PRs that introduce changes in governance, tech debt and chores (linting setup, baseline, etc.) | PR automation | -| tests | PRs that add or change tests | PR automation | -| dependencies | Changes that touch dependencies, e.g. Dependabot, etc. | Issues/PR automation | -| breaking-change | Changes that will cause customer impact and need careful triage | | -| blocked | Items which progress is blocked by external dependency or reason | | -| confirmed | Items with clear scope and that are ready for implementation | | -| discussing | Items that need to be discussed, elaborated, or refined | | -| on-hold | Items that are on hold and will be revisited in the future | | -| pending-release | Merged changes that will be available soon | Release automation auto-closes/notifies it | -| completed | Items that are complete and have been merged and/or shipped | | -| rejected | This is something we will not be working on. At least, not in the measurable future | | -| 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 related 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/main/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/main/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 `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.aws.amazon.com/powertools/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 `bug` with `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/discussions/new?category=rfcs)? -- Does the match our [Tenets](https://docs.aws.amazon.com/powertools/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) - -### Reserving a package name on npm - -When a brand-new package is about to be merged into `main` for the first time (e.g. a new utility), its name must be manually published to npm **once**, ahead of its first real release. - -!!! important - The `Make Release` workflow publishes packages using [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers){target="_blank" rel="nofollow"} via GitHub Actions OIDC, so we get provenance/attestation without storing a long-lived `NPM_TOKEN`. - - Trusted publishers can only be configured for a package that **already exists** on npm (under `npmjs.com/package//access`), so a package can't reserve its own name this way the first time around. - - A maintainer must publish an initial placeholder version manually to reserve the name and unlock Trusted Publishing for it. - -Follow these steps before the new package's first real release: - -1. **Create a temporary local package** using the same placeholder shape adopted by every utility before its first release, for example: - - ```json title="package.json" - { - "name": "@aws-lambda-powertools/", - "version": "0.0.0", - "description": "The package for the Powertools for AWS Lambda (TypeScript) library", - "author": { "name": "Amazon Web Services", "url": "https://aws.amazon.com" }, - "publishConfig": { "access": "public" }, - "homepage": "https://github.com/aws-powertools/powertools-lambda-typescript", - "license": "MIT-0", - "main": "./lib/index.js", - "types": "./lib/index.d.ts", - "files": ["lib"], - "repository": { - "type": "git", - "url": "git+https://github.com/aws-powertools/powertools-lambda-typescript.git" - }, - "bugs": { "url": "https://github.com/aws-powertools/powertools-lambda-typescript/issues" }, - "dependencies": {}, - "keywords": ["aws", "lambda", "powertools", "handler", "nodejs", "serverless"], - "devDependencies": {} - } - ``` - - Add a `README.md` with the same "do not use this in production yet" disclaimer used by other placeholders (see [`@aws-lambda-powertools/validation@0.0.0`](https://www.npmjs.com/package/@aws-lambda-powertools/validation/v/0.0.0){target="_blank" rel="nofollow"} as a reference). - - Also add a `lib/index.js`/`lib/index.d.ts` pair, where the former only logs that it's a placeholder used to reserve the name. - -2. **Authenticate locally** as an npm user who's a member of the `@aws-lambda-powertools` org with publish rights. Use a short-lived, least-privilege token and never commit it to `.npmrc` - remove and rotate/revoke it as soon as you're done. - -3. **Publish with the `pre` dist-tag**, not `latest`: - - ```bash - npm publish --access public --tag pre - ``` - - !!! note - npm always assigns `latest` to the very first version ever published for a package, regardless of `--tag`. This means `0.0.0` will briefly carry both `latest` and `pre`. This is expected and self-corrects: the next real release (published without an explicit tag) will move `latest` forward, while `pre` stays pinned to `0.0.0` as a permanent marker of the placeholder. - -4. **Configure Trusted Publishing** for the new package: go to `https://www.npmjs.com/package//access`, add a Trusted Publisher for GitHub Actions, and point it at this repository and the `make-release.yml` workflow. This is what lets `Make Release` publish real versions of this package with OIDC/provenance going forward, without ever needing an `NPM_TOKEN`. - -5. Make sure the PR adding the new package also adds it to the `workspaces` array in the root `package.json`, and to any workflow that enumerates packages individually (e.g. `reusable-run-linting-check-and-unit-tests.yml`, `run-e2e-tests.yml`), so it's picked up by CI and by the next `Make Release` run. - -Once these steps are done, the new package is released like any other in the [normal release process](#releasing-a-new-version) the next time `Make Release` runs. - -### Releasing a new version - -Releasing a new version is a multi-step process that requires up to 3 hours to complete. Below a checklist of the main steps to follow: - -1. **End to end tests**: Run the [e2e tests](#run-end-to-end-tests) and ensure they pass. -2. **Version bump**: Run the `Make Version` workflow to bump the version. This will create a PR with the new version and -a changelog. Visually inspect the diff and make sure the changelog and version are correct, then merge the PR. Merging -this PR automatically triggers the `Make Release` workflow. -3. **Make Release**: The `Make Release` workflow will: 1/ run the unit tests again, 2/ build and publish to npmjs.com, -3/ build and deploy the Lambda layers to the `Beta` and `Prod` environments in all commercial Regions, 4/ run canary -tests, 5/ deploy the Lambda layers to the `GovCloud` and `China` partitions (Gamma then Prod, both in parallel) once the -commercial Prod deployment finishes, 6/ open a PR to update the documentation with the new layer ARNs once all three -(commercial, GovCloud, China) Prod deployments are complete. -4. **Review and merge docs PR**: Once the `Make Release` workflow is complete, a PR will be created to update the -documentation with the new version. Review and merge this PR. Merging this PR automatically triggers the -`Rebuild latest docs` workflow, which updates the documentation with the new version. - -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. - -#### Release process visualized - -Every release makes dozens of checks, linting, canaries and deployments - all of these are automated through a number of distinct workflows that together make up the release process. - -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, 8s - -section Version - Bump package version : active, 8s - Create commit (version bump) : active, 8s - Open version PR : active, 8s - -Review and merge version PR : milestone, m2 - -section QA - Quality checks : active, 2.4m - -section Build - Bundle release artifact (CJS+ESM) : active, 39s - -section Git release - Git Tag : active, 8s - Push Tag : active, 8s - -section Release - Attest build : active, 8s - Sign attestation : active, attestation, 10:04, 8s - Publish npm.js : active, npm, after attestation, 40s - -npmjs.com release : milestone, m3 - -section Layer release - Build : active, layer_build, 10:05, 2.5m - Deploy Beta : active, layer_beta, after layer_build, 4m - Run Canary Test : active, layer_canary, after layer_beta, 2m - Deploy Prod : active, layer_prod, after layer_canary, 4m - -Layer release : milestone, m4 - -section GovCloud - Publish GovCloud layers (Gamma) : active, govcloud_gamma, after layer_prod, 8s - Publish GovCloud layers (Prod) : active, govcloud_prod, after govcloud_gamma, 8s -GovCloud layers published : milestone, m5 - - -section China - Publish China layers (Gamma) : active, china_gamma, after layer_prod, 8s - Publish China layers (Prod) : active, china_prod, after china_gamma, 8s -China layers published : milestone, m6 - - -section Docs - Create commit (Layer ARN) : active, after govcloud_prod china_prod, 8s - Open docs PR : active, 8s - -Review and merge docs PR : milestone, m7 - - Publish updated docs : active, 2m - -section SSM -Update SSM parameters (Beta) : active, 8s -Update SSM parameters (Prod) : active, 8s - -SSM Parameters updated: milestone, m8 - -section Documentation -Documentation release : milestone, m9 - -Release complete : milestone, m10 -``` - -#### 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 `feature`, `bug`, `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 `pending-release` notified of the new release and labeled as `completed`. - -### Run end to end tests - -E2E tests must be ran before making a release, manually via the [Run e2e Tests workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/run-e2e-tests.yml). Maintainers should also run them manually for large contributions authored by maintainers before merging to `main`. - -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.aws.amazon.com/powertools/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. - -### Publish Lambda Layers to new AWS Regions - -When a new AWS region is available, make the Lambda Layers available in that region. Before doing so, ensure that the region supports AWS Lambda and that the Lambda Layers are compatible with the region. - -Then bootstrap the region both in the beta and prod accounts by running `npm run cdk bootstrap aws:///` for each account while in the `layers` directory. Next, run the [`layer-balancer` script](https://github.com/aws-powertools/powertools-lambda-python/tree/develop/layer/scripts/layer-balancer) to align the layer version in the new region with the existing regions. - -Finally, add the new region to the [`region` matrix](https://github.com/aws-powertools/powertools-lambda-typescript/blob/082b626c31f11138fb36d5724f922980d534c878/.github/workflows/reusable_deploy_layer_stack.yml#L33) in the `reusable_deploy_layer_stack.yml` workflow file, and add the corresponding ARN to the Lambda Layer ARN table in the [documentation](https://github.com/aws-powertools/powertools-lambda-typescript/blob/082b626c31f11138fb36d5724f922980d534c878/docs/index.md?plain=1#L42). - -### 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/main/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 `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. diff --git a/docs/roadmap.md b/docs/roadmap.md deleted file mode 100644 index c294e7921e..0000000000 --- a/docs/roadmap.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Roadmap -description: Public roadmap for Powertools for AWS Lambda (TypeScript) ---- - - - -## Overview - -Our public roadmap outlines the high level direction we are working towards. We update this document when our priorities change: security and stability are our top priority. - -!!! info "For most up-to-date information, see our [board of activities](https://github.com/orgs/aws-powertools/projects/7/views/13?query=is%3Aopen+sort%3Aupdated-desc){target="_blank"}." - -### Key areas - -Security and operational excellence take precedence above all else. This means bug fixing, stability, customer's support, and internal compliance may delay one or more key areas below. - -!!! info "We may choose to reprioritize or defer items based on customer feedback, security, and operational impacts, and business value." - -#### Event Handler REST (p0) - -This is a roadmap item that we carry forward from 2024 and involves the creation of a new utility for customers to work with REST APIs built on AWS Lambda, and Amazon API Gateway REST and HTTP APIs, Application Load Balancer (ALB), Lambda Function URLs, and VPC Lattice. It's one of the most requested features in terms of feature parity from our customers. - -You can follow the progress of this feature in the [Event Handler REST milestone](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/17){target="_blank"}. Below are some of the key macro tasks that we will be working on: - -- [x] [Explore pros & cons of whether to build atop lean frameworks (e.g., Hono) or from scratch](https://github.com/aws-powertools/powertools-lambda-typescript/issues/2409){target="_blank"} -- [x] [RFC to discuss initial thoughts and feasibility for TS/JS ecosystem](https://github.com/aws-powertools/powertools-lambda-typescript/discussions/3500){target="_blank"} -- [ ] Support for API Gateway REST API resolver -- [ ] Support for API Gateway HTTP API resolver -- [ ] Support for Lambda Function URL resolver -- [ ] Support for Application Load Balancer resolver -- [ ] Support for VPC Lattice resolver -- [ ] Support for Data Validation _(e.g., `Zod`)_ -- [ ] Support for OpenAPI generation -- [ ] Support for Middlewares -- [ ] Support for Compression -- [ ] Support for Binary responses -- [ ] Support for custom serializer -- [ ] Support for injecting request details _(consider not doing globals like Python legacy)_ -- [ ] Support for Router _(multi-file routes)_ - -#### Feature parity (p1) - -To close the gap between Powertools for AWS Lambda (Python) and Powertools for AWS Lambda (TypeScript), we will focus our efforts on adding targeted features that are currently missing from the TypeScript version. These include (but are not limited to): - -##### Logger - -- [x] [Ability to add a correlation ID to logs via decorator/middleware](https://github.com/aws-powertools/powertools-lambda-typescript/issues/2863){target="_blank"} -- [x] [Ability to pretty print stack traces](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1362){target="_blank"} -- [x] [Ability to buffer logs](https://github.com/aws-powertools/powertools-lambda-typescript/releases/tag/v2.16.0){target="_blank"} -- [x] [Ability to refresh debug log sampling rate via decorator/middleware](https://github.com/aws-powertools/powertools-lambda-typescript/releases/tag/v2.16.0){target="_blank"} - -##### Event Handler - -In addition to the Event Handler REST feature mentioned above, we will also be working on the following: - -- [x] [Implement resolver for Amazon Bedrock Agents Functions](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3710){target="_blank"} -- [x] [Implement resolver for AWS AppSync Events API](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3857){target="_blank"} -- [ ] ~~Implement resolver for Amazon Bedrock Agents OpenAPI~~ _(won't do - Amazon Bedrock Agents Classic is in [maintenance mode](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-classic-maintenance-mode.html){target="_blank"})_ -- [x] [Create RFC for AppSync GraphQL resolver](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3885){target="_blank"} -- [x] [Implement resolver for AWS AppSync GraphQL API](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1166){target="_blank"} - -##### Validation - -For the Validation utility, we'll experiment with a community-driven approach to building a new Powertools for AWS Lambda utility. - -- [x] [Standalone validation utility](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3607){target="_blank"} -- [x] [Class method decorator validation](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3608){target="_blank"} -- [x] [Middy.js middleware validation](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3609){target="_blank"} -- [x] [Documentation](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3716){target="_blank"} - -##### Other utilities - -- [x] [Support for Valkey- and Redis OSS-compatible cache backends for Idempotency](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3183){target="_blank"} - -#### Governance & Advanced Use Cases (p2) - -To streghten our offering for more advanced customers as well as enterprises, we will be working on a set of activities that will help us better support their needs and practices. These include: - -- [x] [Publish Lambda layers to GovCloud](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3423){target="_blank"} -- [x] [Publish Lambda layers to China regions](https://github.com/aws-powertools/powertools-lambda-typescript/issues/3920){target="_blank"} -- [ ] Improve OSS supply chain posture (Q2) by making sure we're auditing our dependencies for compatible licenses and include NOTICE files in our Lambda layers -- [ ] Create a new "Advanced Use Cases" section in the docs - to help customers with more complex use cases, such as running Powertools for AWS Lambda in container environments -- [ ] Set up CI/CD for performance testing -- [ ] Improve performance of our core utilities -- [ ] [Improve performance overhead of Lambda layers](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1725){target="_blank"} -- [x] [Publish SSM Parameters to lookup Lambda layers ARNs](https://github.com/aws-powertools/powertools-lambda-typescript/releases/tag/v2.14.0){target="_blank"} - -#### Community engagement & new customers (p3) - -To ensure we are attracting tomorrow's customers as well as new contributors to the project, we will be working on a set of activities that will help us better engage with the community and new customers. These include: - -- [x] [Create a new "Getting Started" guide in the docs](https://github.com/aws-powertools/powertools-lambda-typescript/issues/2948){target="_blank"} -- [ ] Further improve the "Contributing" & "How to find contributions" pages -- [ ] Surface contribution opportunities on GitHub Discussions & other community channels -- [ ] Improve release notes announcements on GitHub Discussions & other community channels -- [x] We will also attempt to create a community-developed new utility (see [Validation](#validation) above) - -### Missing something? - -You can help us prioritize by [upvoting existing feature requests](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc++label%3Atype%2Ffeature-request+), leaving a comment on what use cases it could unblock for you, and by joining our discussions on GitHub. - -[![GitHub Discussions](https://img.shields.io/badge/GitHub-Discussions-181717.svg?logo=github)](https://github.com/aws-powertools/powertools-lambda-typescript/discussions) - -### Roadmap status definition - -
-```mermaid -graph LR - Ideas --> Backlog --> Work["Working on it"] --> Merged["Coming soon"] --> Shipped -``` -Visual representation -
- -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. -- **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. - -### Process - -
-```mermaid -graph LR - PFR[Feature request] --> Triage{Need RFC?} - Triage --> |Complex/major change or new utility?| RFC[Ask or write RFC] --> Approval{Approved?} - Triage --> |Minor feature or enhancement?| NoRFC[No RFC required] --> Approval - Approval --> |Yes| Backlog - Approval --> |No | Reject["Inform next steps"] - Backlog --> |Prioritized| Implementation - Backlog --> |Defer| WelcomeContributions["help-wanted label"] -``` -Visual representation -
- -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%2Ffeature-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 template](https://github.com/aws-powertools/powertools-lambda-typescript/discussions/new?category=rfcs){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](./maintainers.md){target="_blank"} document to understand how we triage issues and pull requests, labels and governance." - -### Disclaimer - -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. - -### FAQs - -**Q: Why did you build this?** - -A: We know that our customers are making decisions and plans based on what we are developing, and we want to provide our customers the insights they need to plan. - -**Q: Why are there no dates on your roadmap?** - -A: Because job zero is security and operational stability, we can't provide specific target dates for features. The roadmap is subject to change at any time, and roadmap issues in this repository do not guarantee a feature will be launched as proposed. - -**Q: How can I provide feedback or ask for more information?** - -A: For existing features, you can directly comment on issues. For anything else, please open an issue. diff --git a/docs/versioning.md b/docs/versioning.md index 1a8b6375ae..ef34fb99b0 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -37,8 +37,8 @@ Most AWS SDKs have underlying dependencies, such as language runtimes, AWS Lambd The following terms are used to classify underlying third party dependencies: -* [**AWS Lambda Runtime**](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html): Examples include `nodejs22.x`, `python3.12`, etc. -* **Language Runtime**: Examples include Python 3.12, NodeJS 22, Java 17, .NET Core, etc. +* [**AWS Lambda Runtime**](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html): Examples include `nodejs24.x`, `python3.12`, etc. +* **Language Runtime**: Examples include Python 3.12, Node.js 24, Java 17, .NET Core, etc. * **Third party Library**: Examples include Pydantic, AWS X-Ray SDK, AWS Encryption SDK, Middy.js, etc. Powertools for AWS Lambda follows the [AWS Lambda Runtime deprecation policy cycle](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html#runtime-support-policy), when it comes to Language Runtime. This means we will stop supporting their respective deprecated Language Runtime _(e.g., `nodejs20.x`)_ without increasing the major SDK version. @@ -59,7 +59,7 @@ Each Powertools for AWS Lambda layer adheres to the versioning policy outlined a Maintenance announcements are communicated in several ways: -* A pinned GitHub Request For Comments (RFC) issue indicating the campaign for the next major version. The RFC will outline the path to end-of-support, specify campaign timelines, and upgrade guidance. +* A pinned GitHub Discussion in the RFCs (Request for Comments) category indicating the campaign for the next major version. The RFC will outline the path to end-of-support, specify campaign timelines, and upgrade guidance. * AWS SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. * Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the upgrade guide. diff --git a/docs/we_made_this.md b/docs/we_made_this.md index 593bdd7c87..bdc9c36105 100644 --- a/docs/we_made_this.md +++ b/docs/we_made_this.md @@ -33,7 +33,7 @@ With the index being local searches are super fast and the index is cached for t ### Lambda Powertools - great defaults for batteries that aren't quite (but should be) included -> **Author: [Mike Roberts](mailto:mike@symphonia.io) [:material-twitter:](https://twitter.com/mikebroberts){target="_blank"}** +> **Author: [Mike Roberts](mailto:mike@symphonia.io) [:fontawesome-brands-x-twitter:](https://x.com/mikebroberts){target="_blank"}** This article discusses why you should consider using Powertools in your Lambda functions. @@ -41,7 +41,7 @@ This article discusses why you should consider using Powertools in your Lambda f ### Test Drive AWS Lambda Powertools for Typescript -> **Author: [Matt Lewis](https://twitter.com/m_lewis){target="_blank"} :material-twitter:** +> **Author: [Matt Lewis](https://x.com/m_lewis){target="_blank"} :fontawesome-brands-x-twitter:** This article gives an overview Powertools' core utilities: Logger, Metrics, and Tracer. @@ -57,7 +57,7 @@ Discover how easy it is to quickly “power-up” your Node.js Lambda functions ### Getting to Well Architected Faster with AWS Lambda Powertools -> **Author: [Eoin Shanaghy](https://twitter.com/eoins){target="_blank"} :material-twitter:** +> **Author: [Eoin Shanaghy](https://x.com/eoins){target="_blank"} :fontawesome-brands-x-twitter:** This post shows how to use Powertools for AWS Lambda to quickly build Well-Architected Serverless applications. @@ -65,7 +65,7 @@ This post shows how to use Powertools for AWS Lambda to quickly build Well-Archi ### AWS Lambda Powertools TypeScript -> **Author: [Matt Morgan](https://twitter.com/NullishCoalesce){target="_blank"} :material-twitter:** +> **Author: [Matt Morgan](https://x.com/NullishCoalesce){target="_blank"} :fontawesome-brands-x-twitter:** A two parts series that gives an overview of Powertools and its features starting from the beta phase to the General Availability release. @@ -89,7 +89,7 @@ This article discusses how to use the Idempotency feature to work around EventBr An overview of all the Powertools for AWS Lambda features put into a real world example. - + ### AWS re:Invent 2024 - Gain expert-level knowledge about Powertools for AWS Lambda (OPN402) @@ -97,4 +97,4 @@ An overview of all the Powertools for AWS Lambda features put into a real world Did you learn serverless best practices but are unsure about implementation? Have you used Powertools for AWS Lambda but felt you barely scratched the surface? This session dives deep into observability practices, safe retries with idempotency, mono- and multi-function APIs, and more. Learn about each practice in depth, achieve expert-level knowledge, and hear from maintainers about what’s next. - +