Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.
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.
We welcome you to use the GitHub issue tracker to report bugs or suggest features.
When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
- A reproducible test case or series of steps
- The version of our code being used
- Any modifications you've made relevant to the bug
- Anything unusual about your environment or deployment
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.
- You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already.
- You open an RFC issue to discuss any significant work - we would hate for your time to be wasted.
- You lint and test the code. When you've setup the repository with
npm run init-environment, pre-commit and push-hooks will automatically lint and test the code. Pull request builds will run the same checks as well.
To send us a pull request, please follow these steps:
- Fork the repository.
- Install dependencies:
npm install - Prepare utilities like commit hooks:
npm run init-environment - Create a new branch to focus on the specific change you are contributing e.g.
git checkout -b improv/logger-debug-sampling - Run all tests, and code baseline checks:
npm run test - Commit to your fork using clear commit messages.
- Send us a pull request with a conventional semantic title, and answering any default questions in the pull request interface. Here's an example.
- Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
GitHub provides an additional document on forking a repository and creating a pull request.
You might find useful to run both the documentation website and the API reference locally while contributing:
- API reference: 🚧
- Docs website:
You can build and start a local docs website by running these two commands.
npm run docs-buildDockerImageORdocker build -t squidfunk/mkdocs-material ./docs/npm run docs-runLocalDockerORdocker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
Tests are under tests folder of each modules and split into two categories: unit tests and e2e (end-to-end) tests.
You can run each group separately or all together thanks to jest-runner-groups.
Unit tests, under tests/unit folder are standard Jest tests.
End-to-end tests, under tests/e2e folder, will test the module features by deploying AWS Lambda functions into your AWS Account. We use aws-cdk v1 library (not v2 due to this cdk issue) for Typescript for creating infrastructure, and aws-sdk-js v2 for invoking the functions and assert on the expected behaviors. All steps are also executed by Jest.
Running end-to-end tests will deploy AWS resources. You will need an AWS account and the tests might incur costs. The cost from some services are covered by the AWS Free Tier but not all of them. If you don't have an AWS Account follow these instructions to create one.
When contributing to this repository, these end-to-end tests are run by the maintainers before merging a PR.
Unit tests
Write
As mentioned before, tests are split into groups thanks to jest-runner-groups and therefore each test needs to be tagged properly by adding the following comments in the header of your unit test file:
/**
* Tests metrics
*
* @group unit/<YOUR CATEGORY>/<YOUR SUB CATEGORY>
*/Run
To run unit tests you can either use
- npm task
lerna-test:unit(npm run lerna-test:unit) in root folder to run them all - npm task
test:e2e(npm run test:unit) in module folder (for example:packages/metrics) to run the module specific one - jest directly
npx jest --group=unitin module folder to run the module specific one (You can run selective tests by restricting the group to the one you want. For instancenpx jest --group=unit/metrics/class)
e2e tests
Write
As mentioned in the previous section, tests are split into groups thanks to jest-runner-groups and therefore each test needs to be tagged properly by adding the following comments in the header of your unit test file:
/**
* Tests data lake catalog
*
* @group e2e/<YOUR CATEGORY>/<YOUR SUB CATEGORY>
*/See metrics/tests/e2e/decorator.test.ts as an example.
Run
To run e2e tests you can either use
- npm task
lerna-test:e2e(npm run lerna-test:e2e) in root folder - npm task
test:e2e(npm run test:e2e) in module folder (for example:packages/metrics) to run the module specific one - jest directly
npx jest --group=e2ein module folder. (You can run selective tests by restricting the group to the one you want. For instancenpx jest --group=e2e/metrics/decorator)
Two important env variable can be used:
AWS_PROFILEto use the right AWS credentialsDISABLE_TEARDOWNif you don't want your stack to be destroyed at the end of the test (useful in dev mode when iterating over your code).
Example: DISABLE_TEARDOWN=true AWS_PROFILE=dev-account npx jest --group=e2e/metrics/decorator
Automate
You can run the end-to-end tests automatically on your forked project by following these steps:
-
Create an IAM role in your target AWS account, with the least amount of privilege.
As mentioned above in this page, we are leveraging CDK to deploy and consequently clean-up resources on AWS. Therefore to run those tests through Github actions you will need to grant specific permissions to your workflow.
We recommend following Amazon IAM best practices for the AWS credentials used in GitHub Actions workflows, including:
- Do not store credentials in your repository's code.
- Grant least privilege to the credentials used in GitHub Actions workflows. Grant only the permissions required to perform the actions in your GitHub Actions workflows.
- Monitor the activity of the credentials used in GitHub Actions workflows.
For an example of how to create a role in CDK, you can look at @pahud/cdk-github-oidc construct.
More information about:
-
Add your new role into your Github fork secrets with name
AWS_ROLE_ARN_TO_ASSUME. -
In your forked repository, go to the "Actions" tabs, select the
run-e2e-testsworkflow. -
In the run-e2e-tests workflow page, select "Run workflow" and run it on the desired branch.
⚠️ Don't automatically run end-to-end tests on branch push or PRs. A malicious attacker can submit a pull request to attack your AWS account. Ideally, use a blank account without any important workload/data, and limitAWS_ROLE_ARN_TO_ASSUMEpermission to least minimum privilege.
As part of the repo you will find an examples folder at the root. This folder contains examples (written with CDK for now) of deployable AWS Lambda functions using Powertools.
To test your updates with these examples you just have to:
- Build your local version of aws-lambda-powertools-typescript npm packages with
npm run lerna-package - Update their references in examples
cd examples/cdk npm install ../../packages/**/dist/aws-lambda-powertools-* - Run cdk tests
npm run test - Deploy
npm run cdk deploy
Previous command will deploy AWS resources therefore you will need an AWS account and it might incur in some costs which should be covered by the AWS Free Tier. If you don't have an AWS Account follow these instructions to create one.
| Category | Convention |
|---|---|
| Docstring | We use a slight variation of numpy convention with markdown to help generate more readable API references. |
| Style guide | We use black as well as flake8 extensions to enforce beyond good practices PEP8. We strive to make use of type annotation as much as possible, but don't overdo in creating custom types. |
| Core utilities | Core utilities use a Class, always accept service 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 solving a developer experience problem while following the project Tenets. |
| Exceptions | Specific exceptions live within utilities themselves and use Error suffix e.g. MetricUnitError. |
| Git commits | We follow conventional commits. These are not enforced as we squash and merge PRs, but PR titles are enforced during CI. |
| Documentation | API reference docs are generated from docstrings which should have 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. |
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), looking at any 'help wanted' issues is a great place to start.
This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
TODO
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.