- Reporting bugs and requesting features
- Finding contributions to work on
- Contributing via pull requests
- Code of Conduct
- Security issue notifications
- Licensing
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 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.
Before opening anything new, please check existing open and recently closed issues, so nobody duplicates work. Then pick the entry point that matches what you have:
- Bug report — a runtime error you can reproduce, whether or not you know how to fix it.
- Feature request — a new feature or enhancement that would help you, your team, or other customers.
- Documentation improvement — typos, unclear guides, missing examples, diagrams.
- Maintenance — technical debt, governance, and anything internal.
- Design proposal (RFC) — 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 — blog posts, workshops, talks, and sample apps built with Powertools for AWS Lambda.
- Become a public reference — tell everyone how your organization uses Powertools for AWS Lambda.
- GitHub Discussions — questions, half-formed ideas, and anything that isn't an issue yet.
RFC review is collaborative. Before submitting an RFC, use the RFC template and make sure the proposal:
- Aligns with our 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.
Browsing the open issues is the best place to start. Issues still labelled for triage are being scoped, so comment before picking one up. GitHub Discussions is where questions and design proposals get debated — answering a question there is as valuable as a code change.
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.
Contributions via pull requests are much appreciated. 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 pull requests to make sure someone else hasn't addressed the problem already.
- You discuss and agree the proposed changes under an existing issue 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.
At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated.
timeline
title Code integration journey (CI)
Project setup <br> (npm run setup-local) : Code checkout
: Dependencies
: Git hooks
: Local branch
: Local changes
: Local tests
Pre-commit checks <br> (git commit) : Code linting and formatting
: Markdown linting
Pre-push checks <br> (git push) : Type check tests
: Unit tests with 100% coverage
Pull Request <br> (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)
After merge <br> (CI checks) : Deploy staging docs
: Update draft release
The checks are defined in the lint and unit test, CodeQL, dependency review, and workflow security workflows.
A maintainer may add a do-not-merge label, which blocks the merge until the underlying issue is resolved.
Fork the repository, 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.
Prerequisites:
- Node.js 26.x, the version pinned in
.nvmrc, sonvm useorfnm usepicks 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.
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.
- Create a branch named after the change you are contributing, e.g.
improv/logger-debug-sampling. - Commit to your fork using clear commit messages. Don't worry about the commit format — we squash every pull request on merge.
- 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 runnpx lint-staged,npm run build:tests -ws --if-present, andnpx vitest --run --exclude tests/unit/layer-publisher.test.ts --coverage --coverage.thresholds.100 tests/unitbefore pushing. - Open a pull request with a title that follows the Conventional Commits specification, and fill in every area the pull request template asks for — including the issue it closes.
- Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
First pull request ever? GitHub documents forking a repository and creating a pull request.
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, 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 and the AWS CLI installed and configured. Then, from the repo root:
npm run test:e2e -w packages/metricsruns the end-to-end suites of a single package on the default Node.js runtime.npm run test:e2e:nodejs26x -w packages/metricsruns the same suites pinned to a specific runtime. Node.js 22, 24, and 26 are supported; the default is Node.js 26.
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, which fans the suites out across every supported runtime version and architecture.
You might find useful to run both the documentation website and the API reference locally while contributing:
-
Build the Docker image (only needed the first time):
npm run docs:docker:build
-
Run the documentation website:
npm run docs:docker:run
You can also run the documentation website and API reference locally without Docker. This needs the Python version pinned in docs/.python-version, which is also the version CI uses:
-
Create a virtual environment and install dependencies:
npm run docs:local:setup
The script looks for a
python3.14-style executable. If your interpreter is only available under another name, for example in a conda environment, point the script at it withPYTHON=python npm run docs:local:setup. -
Run the documentation website:
npm run docs:local:run
This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opensource-codeofconduct@amazon.com with any additional questions or comments.
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public GitHub issue.
See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA) for larger changes.