From 9d15a86b7e26c0fbf11d8e98d1c39f662a5f8473 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Tue, 25 Jul 2023 14:39:50 +0200 Subject: [PATCH 01/14] fix(parameters): make cache aware of single vs multiple calls Signed-off-by: heitorlessa --- aws_lambda_powertools/utilities/parameters/base.py | 2 +- aws_lambda_powertools/utilities/parameters/types.py | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/aws_lambda_powertools/utilities/parameters/base.py b/aws_lambda_powertools/utilities/parameters/base.py index 710634636d0..411a2520ae9 100644 --- a/aws_lambda_powertools/utilities/parameters/base.py +++ b/aws_lambda_powertools/utilities/parameters/base.py @@ -27,7 +27,7 @@ from aws_lambda_powertools.shared import constants, user_agent from aws_lambda_powertools.shared.functions import resolve_max_age -from aws_lambda_powertools.utilities.parameters.types import TransformOptions +from aws_lambda_powertools.utilities.parameters.types import RecursiveOptions, TransformOptions from .exceptions import GetParameterError, TransformParameterError diff --git a/aws_lambda_powertools/utilities/parameters/types.py b/aws_lambda_powertools/utilities/parameters/types.py index faa06cee89e..a916f1a344d 100644 --- a/aws_lambda_powertools/utilities/parameters/types.py +++ b/aws_lambda_powertools/utilities/parameters/types.py @@ -1,3 +1,4 @@ from aws_lambda_powertools.shared.types import Literal TransformOptions = Literal["json", "binary", "auto", None] +RecursiveOptions = Literal[True, False] From d47a9f858f9665b89797507aba22404534723feb Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Tue, 25 Jul 2023 15:16:51 +0200 Subject: [PATCH 02/14] chore: cleanup, add test for single and nested Signed-off-by: heitorlessa --- aws_lambda_powertools/utilities/parameters/base.py | 2 +- aws_lambda_powertools/utilities/parameters/types.py | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/aws_lambda_powertools/utilities/parameters/base.py b/aws_lambda_powertools/utilities/parameters/base.py index 411a2520ae9..710634636d0 100644 --- a/aws_lambda_powertools/utilities/parameters/base.py +++ b/aws_lambda_powertools/utilities/parameters/base.py @@ -27,7 +27,7 @@ from aws_lambda_powertools.shared import constants, user_agent from aws_lambda_powertools.shared.functions import resolve_max_age -from aws_lambda_powertools.utilities.parameters.types import RecursiveOptions, TransformOptions +from aws_lambda_powertools.utilities.parameters.types import TransformOptions from .exceptions import GetParameterError, TransformParameterError diff --git a/aws_lambda_powertools/utilities/parameters/types.py b/aws_lambda_powertools/utilities/parameters/types.py index a916f1a344d..faa06cee89e 100644 --- a/aws_lambda_powertools/utilities/parameters/types.py +++ b/aws_lambda_powertools/utilities/parameters/types.py @@ -1,4 +1,3 @@ from aws_lambda_powertools.shared.types import Literal TransformOptions = Literal["json", "binary", "auto", None] -RecursiveOptions = Literal[True, False] From 3f0f04a9f6e1b8a3fb37f737ab42f6631ebaaabb Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 18 Sep 2023 17:58:19 -0400 Subject: [PATCH 03/14] docs: contributing guide skeleton --- docs/contributing/documentation/api_guide.md | 8 + docs/contributing/documentation/rfcs.md | 8 + docs/contributing/documentation/tutorials.md | 8 + docs/contributing/documentation/user_guide.md | 8 + docs/contributing/getting_started.md | 172 ++++++++++++++++++ docs/contributing/index.md | 172 ++++++++++++++++++ docs/contributing/setup.md | 34 ++++ docs/contributing/testing/e2e_tests.md | 18 ++ docs/contributing/testing/functional_tests.md | 18 ++ docs/contributing/testing/unit_tests.md | 18 ++ .../tracks/casual_regular_contributor.md | 8 + docs/contributing/tracks/customer_advocate.md | 8 + docs/contributing/tracks/overview.md | 8 + mkdocs.yml | 17 ++ 14 files changed, 505 insertions(+) create mode 100644 docs/contributing/documentation/api_guide.md create mode 100644 docs/contributing/documentation/rfcs.md create mode 100644 docs/contributing/documentation/tutorials.md create mode 100644 docs/contributing/documentation/user_guide.md create mode 100644 docs/contributing/getting_started.md create mode 100644 docs/contributing/index.md create mode 100644 docs/contributing/setup.md create mode 100644 docs/contributing/testing/e2e_tests.md create mode 100644 docs/contributing/testing/functional_tests.md create mode 100644 docs/contributing/testing/unit_tests.md create mode 100644 docs/contributing/tracks/casual_regular_contributor.md create mode 100644 docs/contributing/tracks/customer_advocate.md create mode 100644 docs/contributing/tracks/overview.md diff --git a/docs/contributing/documentation/api_guide.md b/docs/contributing/documentation/api_guide.md new file mode 100644 index 00000000000..7e7e10085bf --- /dev/null +++ b/docs/contributing/documentation/api_guide.md @@ -0,0 +1,8 @@ +--- +title: Writing API guide documentation +description: Contributing API documentation to Powertools for AWS Lambda (Python) +--- + +## TBW + +Something great will come. diff --git a/docs/contributing/documentation/rfcs.md b/docs/contributing/documentation/rfcs.md new file mode 100644 index 00000000000..6d344daceea --- /dev/null +++ b/docs/contributing/documentation/rfcs.md @@ -0,0 +1,8 @@ +--- +title: Writing Request For Comment (RFC) +description: Contributing RFCs to Powertools for AWS Lambda (Python) +--- + +## TBW + +Something great will come. diff --git a/docs/contributing/documentation/tutorials.md b/docs/contributing/documentation/tutorials.md new file mode 100644 index 00000000000..0cdaa2978d5 --- /dev/null +++ b/docs/contributing/documentation/tutorials.md @@ -0,0 +1,8 @@ +--- +title: Writing tutorials +description: Contributing tutorials to Powertools for AWS Lambda (Python) +--- + +## TBW + +Something great will come. diff --git a/docs/contributing/documentation/user_guide.md b/docs/contributing/documentation/user_guide.md new file mode 100644 index 00000000000..41c5653d264 --- /dev/null +++ b/docs/contributing/documentation/user_guide.md @@ -0,0 +1,8 @@ +--- +title: Writing user guide documentation +description: Contributing documentation to Powertools for AWS Lambda (Python) +--- + +## TBW + +Something great will come. diff --git a/docs/contributing/getting_started.md b/docs/contributing/getting_started.md new file mode 100644 index 00000000000..16f2768c3d9 --- /dev/null +++ b/docs/contributing/getting_started.md @@ -0,0 +1,172 @@ +--- +title: Your first contribution +description: All you need to know for your first contribution to Powertools for AWS Lambda (Python) +--- + +## Contributing Guidelines + + +Thank you for your interest in contributing to our project. Whether it's a [bug report](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=bug%2Ctriage&projects=&template=bug_report.yml&title=Bug%3A+TITLE), [new feature](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2Ctriage&projects=&template=feature_request.yml&title=Feature+request%3A+TITLE), [correction](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose), or [additional documentation](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=documentation%2Ctriage&projects=&template=documentation_improvements.yml&title=Docs%3A+TITLE), we greatly value feedback and contributions from our community. + + +Please read through this document before submitting any issues or pull requests to ensure we have all the necessary +information to effectively respond to your bug report or contribution. + +## Reporting Bugs/Feature Requests + +We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements. + + +[When filing an issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose), please check [existing open](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc), or [recently closed](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed), issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. + + +## Contributing via Pull Requests + +Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: + +1. You are working against the latest source on the **develop** branch. +2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already. +3. You open an [issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose) 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. + +```mermaid +timeline + title Code integration journey (CI) + Project setup
(make dev) : Code checkout + : Virtual environment + : Dependencies + : Git pre-commit hooks + : Local branch + : Local changes + : Local tests + + Pre-commit checks
(git commit) : Merge conflict check + : Trailing whitespaces + : TOML checks + : Code linting (standards) + : Markdown linting + : CloudFormation linting + : GitHub Actions linting + : Terraform linting + : Secrets linting + + Pre-Pull Request
(make pr) : Code linting + : Docs linting + : Static typing analysis + : Tests (unit|functional|perf) + : Security baseline + : Complexity baseline + : +pre-commit checks + + Pull Request
(CI checks) : Semantic PR title check + : Related issue check + : Acknowledgment check + : Code coverage diff + : Contribution size check + : Contribution category check + : Dependency vulnerability check + : GitHub Actions security check + : +pre-pull request checks + + After merge
(CI checks) : End-to-end tests + : Longer SAST check + : Security posture check (scorecard) + : GitHub Actions security check + : Rebuild Changelog + : Deploy staging docs + : Update draft release +``` + +### Dev setup + +[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/from-referrer/) + +Firstly, [fork the repository](https://github.com/aws-powertools/powertools-lambda-python/fork). + +To setup your development environment, we recommend using our pre-configured Cloud environment: . Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly. + +Alternatively, you can use `make dev` within your local virtual environment. + +To send us a pull request, please follow these steps: + +1. Create a new branch to focus on the specific change you are contributing e.g. `improv/logger-debug-sampling` +2. Run all tests, and code baseline checks: `make pr` + - Git hooks will run linting and formatting while `make pr` run deep checks that also run in the CI process +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-python/pull/67), and answering any default questions in the pull request interface. +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/). + +### Local documentation + +You might find useful to run both the documentation website and the API reference locally while contributing: + +- **API reference**: `make docs-api-local` +- **Docs website**: `make docs-local` + - If you prefer using Docker: `make docs-local-docker` + +## Conventions + +### General terminology and practices + +| 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 [Ruff](https://beta.ruff.rs/docs/) to enforce beyond good practices [PEP8](https://pep8.org/). We use type annotations and enforce static type checking at CI (mypy). | +| **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](https://docs.powertools.aws.dev/lambda/python/#tenets). | +| **Exceptions** | Specific exceptions live within utilities themselves and use `Error` suffix e.g. `MetricUnitError`. | +| **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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | +| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | +| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | +| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | + +**NOTE**: Functional 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 the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), [looking at any 'help wanted' issues is a great place to start](https://github.com/orgs/aws-powertools/projects/3/views/5?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). +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 ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. + +## Troubleshooting + +### API reference documentation + +When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: `Module aws_lambda_powertools not found`. + +This happens when: + +- You did not install the local dev environment yet + - You can install dev deps with `make dev` command +- The code in the repository is raising an exception while the `pdoc` is scanning the codebase + - Unfortunately, this exception is not shown to you, but if you run, `poetry run pdoc --pdf aws_lambda_powertools`, the exception is shown and you can prevent the exception from being raised + - Once resolved the documentation should load correctly again + +## Licensing + +See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. + +We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. diff --git a/docs/contributing/index.md b/docs/contributing/index.md new file mode 100644 index 00000000000..cb7b9738109 --- /dev/null +++ b/docs/contributing/index.md @@ -0,0 +1,172 @@ +--- +title: Contributing +description: Contributing to Powertools for AWS Lambda (Python) +--- + +## Contributing Guidelines + + +Thank you for your interest in contributing to our project. Whether it's a [bug report](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=bug%2Ctriage&projects=&template=bug_report.yml&title=Bug%3A+TITLE), [new feature](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2Ctriage&projects=&template=feature_request.yml&title=Feature+request%3A+TITLE), [correction](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose), or [additional documentation](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=documentation%2Ctriage&projects=&template=documentation_improvements.yml&title=Docs%3A+TITLE), we greatly value feedback and contributions from our community. + + +Please read through this document before submitting any issues or pull requests to ensure we have all the necessary +information to effectively respond to your bug report or contribution. + +## Reporting Bugs/Feature Requests + +We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements. + + +[When filing an issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose), please check [existing open](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc), or [recently closed](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed), issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. + + +## Contributing via Pull Requests + +Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: + +1. You are working against the latest source on the **develop** branch. +2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already. +3. You open an [issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose) 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. + +```mermaid +timeline + title Code integration journey (CI) + Project setup
(make dev) : Code checkout + : Virtual environment + : Dependencies + : Git pre-commit hooks + : Local branch + : Local changes + : Local tests + + Pre-commit checks
(git commit) : Merge conflict check + : Trailing whitespaces + : TOML checks + : Code linting (standards) + : Markdown linting + : CloudFormation linting + : GitHub Actions linting + : Terraform linting + : Secrets linting + + Pre-Pull Request
(make pr) : Code linting + : Docs linting + : Static typing analysis + : Tests (unit|functional|perf) + : Security baseline + : Complexity baseline + : +pre-commit checks + + Pull Request
(CI checks) : Semantic PR title check + : Related issue check + : Acknowledgment check + : Code coverage diff + : Contribution size check + : Contribution category check + : Dependency vulnerability check + : GitHub Actions security check + : +pre-pull request checks + + After merge
(CI checks) : End-to-end tests + : Longer SAST check + : Security posture check (scorecard) + : GitHub Actions security check + : Rebuild Changelog + : Deploy staging docs + : Update draft release +``` + +### Dev setup + +[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/from-referrer/) + +Firstly, [fork the repository](https://github.com/aws-powertools/powertools-lambda-python/fork). + +To setup your development environment, we recommend using our pre-configured Cloud environment: . Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly. + +Alternatively, you can use `make dev` within your local virtual environment. + +To send us a pull request, please follow these steps: + +1. Create a new branch to focus on the specific change you are contributing e.g. `improv/logger-debug-sampling` +2. Run all tests, and code baseline checks: `make pr` + - Git hooks will run linting and formatting while `make pr` run deep checks that also run in the CI process +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-python/pull/67), and answering any default questions in the pull request interface. +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/). + +### Local documentation + +You might find useful to run both the documentation website and the API reference locally while contributing: + +- **API reference**: `make docs-api-local` +- **Docs website**: `make docs-local` + - If you prefer using Docker: `make docs-local-docker` + +## Conventions + +### General terminology and practices + +| 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 [Ruff](https://beta.ruff.rs/docs/) to enforce beyond good practices [PEP8](https://pep8.org/). We use type annotations and enforce static type checking at CI (mypy). | +| **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](https://docs.powertools.aws.dev/lambda/python/#tenets). | +| **Exceptions** | Specific exceptions live within utilities themselves and use `Error` suffix e.g. `MetricUnitError`. | +| **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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | +| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | +| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | +| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | + +**NOTE**: Functional 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 the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), [looking at any 'help wanted' issues is a great place to start](https://github.com/orgs/aws-powertools/projects/3/views/5?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). +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 ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. + +## Troubleshooting + +### API reference documentation + +When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: `Module aws_lambda_powertools not found`. + +This happens when: + +- You did not install the local dev environment yet + - You can install dev deps with `make dev` command +- The code in the repository is raising an exception while the `pdoc` is scanning the codebase + - Unfortunately, this exception is not shown to you, but if you run, `poetry run pdoc --pdf aws_lambda_powertools`, the exception is shown and you can prevent the exception from being raised + - Once resolved the documentation should load correctly again + +## Licensing + +See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. + +We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md new file mode 100644 index 00000000000..b12505b4241 --- /dev/null +++ b/docs/contributing/setup.md @@ -0,0 +1,34 @@ +--- +title: Development environment +description: Setting up your development environment for contribution +--- + +## Dev setup + +[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/from-referrer/) + +Firstly, [fork the repository](https://github.com/aws-powertools/powertools-lambda-python/fork). + +To setup your development environment, we recommend using our pre-configured Cloud environment: . Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly. + +Alternatively, you can use `make dev` within your local virtual environment. + +To send us a pull request, please follow these steps: + +1. Create a new branch to focus on the specific change you are contributing e.g. `improv/logger-debug-sampling` +2. Run all tests, and code baseline checks: `make pr` + - Git hooks will run linting and formatting while `make pr` run deep checks that also run in the CI process +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-python/pull/67), and answering any default questions in the pull request interface. +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/). + +### Local documentation + +You might find useful to run both the documentation website and the API reference locally while contributing: + +- **API reference**: `make docs-api-local` +- **Docs website**: `make docs-local` + - If you prefer using Docker: `make docs-local-docker` diff --git a/docs/contributing/testing/e2e_tests.md b/docs/contributing/testing/e2e_tests.md new file mode 100644 index 00000000000..a7a519de101 --- /dev/null +++ b/docs/contributing/testing/e2e_tests.md @@ -0,0 +1,18 @@ +--- +title: Writing unit tests +description: Contributing unit tests to Powertools for AWS Lambda (Python) +--- + +### 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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | +| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | +| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | +| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | + +**NOTE**: Functional 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. diff --git a/docs/contributing/testing/functional_tests.md b/docs/contributing/testing/functional_tests.md new file mode 100644 index 00000000000..0365fe7d164 --- /dev/null +++ b/docs/contributing/testing/functional_tests.md @@ -0,0 +1,18 @@ +--- +title: Writing functional tests +description: Contributing functional tests to Powertools for AWS Lambda (Python) +--- + +### 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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | +| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | +| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | +| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | + +**NOTE**: Functional 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. diff --git a/docs/contributing/testing/unit_tests.md b/docs/contributing/testing/unit_tests.md new file mode 100644 index 00000000000..a7a519de101 --- /dev/null +++ b/docs/contributing/testing/unit_tests.md @@ -0,0 +1,18 @@ +--- +title: Writing unit tests +description: Contributing unit tests to Powertools for AWS Lambda (Python) +--- + +### 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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | +| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | +| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | +| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | + +**NOTE**: Functional 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. diff --git a/docs/contributing/tracks/casual_regular_contributor.md b/docs/contributing/tracks/casual_regular_contributor.md new file mode 100644 index 00000000000..9f564954e40 --- /dev/null +++ b/docs/contributing/tracks/casual_regular_contributor.md @@ -0,0 +1,8 @@ +--- +title: Becoming a regular contributor +description: From casual contributions to regular contributor in Powertools for AWS Lambda (Python) +--- + +## TBW + +Something great will come. diff --git a/docs/contributing/tracks/customer_advocate.md b/docs/contributing/tracks/customer_advocate.md new file mode 100644 index 00000000000..857d87ab55a --- /dev/null +++ b/docs/contributing/tracks/customer_advocate.md @@ -0,0 +1,8 @@ +--- +title: Becoming an advocate +description: From customer to Powertools for AWS Lambda (Python) advocate +--- + +## TBW + +Something great will come. diff --git a/docs/contributing/tracks/overview.md b/docs/contributing/tracks/overview.md new file mode 100644 index 00000000000..ab41f3dd61a --- /dev/null +++ b/docs/contributing/tracks/overview.md @@ -0,0 +1,8 @@ +--- +title: Tracks overview +description: Overview of different tracks when contributing to Powertools for AWS Lambda (Python) advocate +--- + +## TBW + +Something great will come. diff --git a/mkdocs.yml b/mkdocs.yml index 1b9f4545239..d32ed214439 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,6 +40,23 @@ nav: - Automation: automation.md - Roadmap: roadmap.md - Maintainers: maintainers.md + - Contributing: + - contributing/index.md + - Development environment: contributing/setup.md + - Your first contribution: contributing/getting_started.md + - Testing: + - Unit tests: contributing/testing/unit_tests.md + - Functional tests: contributing/testing/functional_tests.md + - End-to-end tests: contributing/testing/e2e_tests.md + - Documentation: + - User guide: contributing/documentation/user_guide.md + - API guide: contributing/documentation/api_guide.md + - Tutorials: contributing/documentation/tutorials.md + - Request For Comments (RFC): contributing/documentation/rfc.md + - Tracks: + - Overview: contributing/tracks/overview.md + - Casual to regular contributor: contributing/tracks/casual_regular_contributor.md + - Customer to advocate: contributing/tracks/customer_advocate.md theme: name: material From 221113ef42c4c2a2a7513ed8cef2cc63d46c0cea Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Tue, 19 Sep 2023 16:19:26 -0400 Subject: [PATCH 04/14] docs: dev environment section ready Signed-off-by: heitorlessa --- Makefile | 1 + docs/contributing/setup.md | 89 ++++++++++++++++++++++++++++++-------- 2 files changed, 72 insertions(+), 18 deletions(-) diff --git a/Makefile b/Makefile index 5bfbf031949..c2c4a188b83 100644 --- a/Makefile +++ b/Makefile @@ -6,6 +6,7 @@ target: dev: pip install --upgrade pip pre-commit poetry + poetry config --local virtualenvs.in-project true @$(MAKE) dev-version-plugin poetry install --extras "all" pre-commit install diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index b12505b4241..3e84cf3e41f 100644 --- a/docs/contributing/setup.md +++ b/docs/contributing/setup.md @@ -3,32 +3,85 @@ title: Development environment description: Setting up your development environment for contribution --- -## Dev setup + -[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/from-referrer/) +[![Join our Discord](https://dcbadge.vercel.app/api/server/B8zZKbbyET)](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"} -Firstly, [fork the repository](https://github.com/aws-powertools/powertools-lambda-python/fork). +This page describes how to setup your development environment (Cloud or locally) to contribute to Powertools for AWS Lambda. -To setup your development environment, we recommend using our pre-configured Cloud environment: . Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly. +
+```mermaid +graph LR + Dev["Development environment"] --> Quality["Run quality checks locally"] --> PR["Prepare pull request"] --> Collaborate +``` +End-to-end process +
-Alternatively, you can use `make dev` within your local virtual environment. +## Requirements -To send us a pull request, please follow these steps: +!!! 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"}. -1. Create a new branch to focus on the specific change you are contributing e.g. `improv/logger-debug-sampling` -2. Run all tests, and code baseline checks: `make pr` - - Git hooks will run linting and formatting while `make pr` run deep checks that also run in the CI process -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-python/pull/67), and answering any default questions in the pull request interface. -5. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. +Unless you're using the pre-configured Cloud environment, you'll need the following installed: -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/). +* [x] [GitHub account](https://github.com/join){target="_blank" rel="nofollow"}. You'll need to be able to fork, clone, and contribute via pull request. +* [x] [Python 3.8+](https://www.python.org/downloads/){target="_blank" rel="nofollow"}. Pick any version supported in [AWS Lambda runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). +* [x] [Docker](https://docs.docker.com/engine/install/){target="_blank" rel="nofollow"}. We use it to run documentation linters and non-Python tooling. +* [x] [Fork the repository](https://github.com/aws-powertools/powertools-lambda-python/fork). You'll work against your fork of this repository. -### Local documentation +??? note "Additional requirements if running end-to-end tests" + + * [x] [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites){target="_blank"} + * [x] [AWS Account bootstrapped with CDK](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html){target="_blank"} + * [x] [AWS CLI installed and configured](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + +## Cloud environment + +> **NOTE**. Be mindful of [Gitpod pricing structure](https://www.gitpod.io/pricing){target="_blank" rel="nofollow"} for long-running contributions. When in doubt, use the local environment below. + +To use a pre-configured environment, replace `YOUR_USERNAME` with your GitHub username or organization. + +```bash +https://gitpod.io/#https://github.com/YOUR_USERNAME/powertools-lambda-python #(1)! +``` + +1. For example, my username is `heitorlessa`.

Therefore, my final URL should be `https://gitpod.io/#https://github.com/heitorlessa/powertools-lambda-python` + +Once provisioned, it'll install all development dependencies and tools you'll need to contribute. + +## Local environment + +> Assuming you've got all [requirements](#requirements). + +You can use `make dev` to create a local virtual environment and install all dependencies locally. + +!!! note "Curious about what `make dev` does under the hood?" + We use `Make` to [automate common tasks](https://github.com/aws-powertools/powertools-lambda-python/blob/1ebe3275a5c53aed5a8eb76318e7d0af2367edfa/Makefile#L7){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: -- **API reference**: `make docs-api-local` -- **Docs website**: `make docs-local` - - If you prefer using Docker: `make docs-local-docker` +* **Docs website**: `make docs-local` + * If you prefer using Docker: `make docs-local-docker` +* **API reference**: `make docs-api-local` + +## 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: + +1. You are working against the latest source on the **develop** branch. +2. You check existing [open, and recently merged](https://github.com/aws-powertools/powertools-lambda-python/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. +3. You open an [issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose){target="_blank" rel="nofollow"} before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful. +4. 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. Run all code quality, tests, and baseline checks: `make pr` +2. Commit to your fork using clear commit messages. Don't worry about typos, we will squash all commits during merge. +3. Send us a pull request with a [conventional semantic title](https://github.com/aws-powertools/powertools-lambda-python/pull/67). We prepared a set of questions you can answer in GitHub User Interface to make reviewing easier. +4. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. From 878c74a28923c7136d715e1d762ca37dc96a5b8f Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Wed, 20 Sep 2023 10:17:23 -0400 Subject: [PATCH 05/14] docs: add types of contributions Signed-off-by: heitorlessa --- docs/contributing/getting_started.md | 138 ++++++--------------------- 1 file changed, 31 insertions(+), 107 deletions(-) diff --git a/docs/contributing/getting_started.md b/docs/contributing/getting_started.md index 16f2768c3d9..7d767b07dec 100644 --- a/docs/contributing/getting_started.md +++ b/docs/contributing/getting_started.md @@ -3,110 +3,39 @@ title: Your first contribution description: All you need to know for your first contribution to Powertools for AWS Lambda (Python) --- -## Contributing Guidelines + - -Thank you for your interest in contributing to our project. Whether it's a [bug report](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=bug%2Ctriage&projects=&template=bug_report.yml&title=Bug%3A+TITLE), [new feature](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2Ctriage&projects=&template=feature_request.yml&title=Feature+request%3A+TITLE), [correction](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose), or [additional documentation](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=documentation%2Ctriage&projects=&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 - we couldn't be more excited! -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. +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 contribution. -## Reporting Bugs/Feature Requests +**TODO** -We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements. +* [x] Types of contributions (slide as example); make a table +* [ ] How contributions are licensed etc - confirm whether we can remove CLAs mention +* [ ] Refer to licensing within sending a PR section - -[When filing an issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose), please check [existing open](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc), or [recently closed](https://github.com/aws-powertools/powertools-lambda-python/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. - +## Types of contributions -## Contributing via Pull Requests +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](../../LICENSE){target="_blank"}, and [Code of Conduct](#code-of-conduct). -Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: +Whether you're new contributor or a pro, we compiled a list of the common contributions to help you choose your first: -1. You are working against the latest source on the **develop** branch. -2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already. -3. You open an [issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose) 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. +!!! info "Please check [existing open](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc){target='_blank'}, or [recently closed](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed){target='_blank'} issues before creating a new one." + Each type link goes to their respective template, or Discord invite. -At a high level, these are the steps to get code merged in the repository - don't worry, nearly all of them are automated. - -```mermaid -timeline - title Code integration journey (CI) - Project setup
(make dev) : Code checkout - : Virtual environment - : Dependencies - : Git pre-commit hooks - : Local branch - : Local changes - : Local tests - - Pre-commit checks
(git commit) : Merge conflict check - : Trailing whitespaces - : TOML checks - : Code linting (standards) - : Markdown linting - : CloudFormation linting - : GitHub Actions linting - : Terraform linting - : Secrets linting - - Pre-Pull Request
(make pr) : Code linting - : Docs linting - : Static typing analysis - : Tests (unit|functional|perf) - : Security baseline - : Complexity baseline - : +pre-commit checks - - Pull Request
(CI checks) : Semantic PR title check - : Related issue check - : Acknowledgment check - : Code coverage diff - : Contribution size check - : Contribution category check - : Dependency vulnerability check - : GitHub Actions security check - : +pre-pull request checks - - After merge
(CI checks) : End-to-end tests - : Longer SAST check - : Security posture check (scorecard) - : GitHub Actions security check - : Rebuild Changelog - : Deploy staging docs - : Update draft release -``` - -### Dev setup - -[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/from-referrer/) - -Firstly, [fork the repository](https://github.com/aws-powertools/powertools-lambda-python/fork). - -To setup your development environment, we recommend using our pre-configured Cloud environment: . Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly. - -Alternatively, you can use `make dev` within your local virtual environment. - -To send us a pull request, please follow these steps: - -1. Create a new branch to focus on the specific change you are contributing e.g. `improv/logger-debug-sampling` -2. Run all tests, and code baseline checks: `make pr` - - Git hooks will run linting and formatting while `make pr` run deep checks that also run in the CI process -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-python/pull/67), and answering any default questions in the pull request interface. -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/). - -### Local documentation - -You might find useful to run both the documentation website and the API reference locally while contributing: - -- **API reference**: `make docs-api-local` -- **Docs website**: `make docs-local` - - If you prefer using Docker: `make docs-local-docker` +| Type | Description | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [Documentation](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=documentation%2Ctriage&projects=&template=documentation_improvements.yml&title=Docs%3A+TITLE){target="_blank" rel="nofollow"} | Ideas to make user guide or API guide clearer. It generally go from typos, diagrams, tutorials, the lack of documentation, etc. | +| [Feature request](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2Ctriage&projects=&template=feature_request.yml&title=Feature+request%3A+TITLE){target="_blank" rel="nofollow"} | New functionalities or enhancements that could help you, your team, existing and future customers. Check out our [process to understand how we prioritize it](../roadmap.md#process){target="_blank"}. | +| [Design proposals](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=RFC%2Ctriage&projects=&template=rfc.yml&title=RFC%3A+TITLE){target="_blank" rel="nofollow"} | Request for Comments (RFC) including user experience (UX) based on a feature request to gather the community feedback, and demonstrate the art of the possible. | +| [Bug report](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=bug%2Ctriage&projects=&template=bug_report.yml&title=Bug%3A+TITLE){target="_blank" rel="nofollow"} | A runtime error that is reproducible whether you have an idea how to solve it or not. | +| [Advocacy](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=community-content&projects=&template=share_your_work.yml&title=%5BI+Made+This%5D%3A+%3CTITLE%3E){target="_blank" rel="nofollow"} | Share what you did with Powertools for AWS Lambda. Blog posts, workshops, presentation, sample applications, podcasts, etc. | +| [Public reference](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=customer-reference&projects=&template=support_powertools.yml&title=%5BSupport+Powertools+for+AWS+Lambda+%28Python%29%5D%3A+%3Cyour+organization+name%3E){target="_blank" rel="nofollow"} | Become a public reference to share how you're using Powertools for AWS Lambda at your organization. | +| [Discussions](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"} | Kick off a discussion on Discord, introduce yourself, and help respond to existing questions from the community. | +| [Static typing](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=typing%2Ctriage&projects=&template=static_typing.yml&title=Static+typing%3A+TITLE){target="_blank" rel="nofollow"} | Improvements to increase or correct static typing coverage to ease maintenance, autocompletion, etc. | +| [Technical debt](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=tech-debt%2Ctriage&projects=&template=tech_debt.yml&title=Tech+debt%3A+TITLE){target="_blank" rel="nofollow"} | Suggest areas to address technical debt that could make maintenance easier or provide customer value faster. Generally used by maintainers and contributors. | +| [Governance](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=internal%2Ctriage&projects=&template=maintenance.yml&title=Maintenance%3A+TITLE){target="_blank" rel="nofollow"} | Ideas to improve to our governance processes, automation, and anything internal. Typically used by maintainers and regular contributors. | ## Conventions @@ -143,7 +72,8 @@ Looking at the existing issues is a great way to find something to contribute on ## Code of Conduct -This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/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. @@ -159,14 +89,8 @@ When you are working on the codebase and you use the local API reference documen This happens when: -- You did not install the local dev environment yet - - You can install dev deps with `make dev` command -- The code in the repository is raising an exception while the `pdoc` is scanning the codebase - - Unfortunately, this exception is not shown to you, but if you run, `poetry run pdoc --pdf aws_lambda_powertools`, the exception is shown and you can prevent the exception from being raised - - Once resolved the documentation should load correctly again - -## Licensing - -See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. - -We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. +* You did not install the local dev environment yet + * You can install dev deps with `make dev` command +* The code in the repository is raising an exception while the `pdoc` is scanning the codebase + * Unfortunately, this exception is not shown to you, but if you run, `poetry run pdoc --pdf aws_lambda_powertools`, the exception is shown and you can prevent the exception from being raised + * Once resolved the documentation should load correctly again From 17658519af22bcf93072d2d9467f1e362ff3b6e9 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Wed, 20 Sep 2023 10:26:55 -0400 Subject: [PATCH 06/14] docs: split up conventions into its own doc for growth Signed-off-by: heitorlessa --- docs/contributing/conventions.md | 34 ++++++++++++++++++++++++++++ docs/contributing/getting_started.md | 29 ------------------------ mkdocs.yml | 1 + 3 files changed, 35 insertions(+), 29 deletions(-) create mode 100644 docs/contributing/conventions.md diff --git a/docs/contributing/conventions.md b/docs/contributing/conventions.md new file mode 100644 index 00000000000..23db25b9ad7 --- /dev/null +++ b/docs/contributing/conventions.md @@ -0,0 +1,34 @@ +--- +title: Conventions +description: General conventions and practices that are applicable throughout to Powertools for AWS Lambda (Python) +--- + + + +## 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 [Numpy convention](https://numpydoc.readthedocs.io/en/latest/format.html){target="_blank"} with markdown 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 black and [Ruff](https://beta.ruff.rs/docs/) to enforce beyond good practices [PEP8](https://pep8.org/). We use type annotations and enforce static type checking at CI (mypy). | +| **Core utilities** | Core utilities 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 community needs: development productivity, industry leading practices, etc. Both core and general utilities follow our [Tenets](https://docs.powertools.aws.dev/lambda/python/#tenets). | +| **Exceptions** | Specific exceptions live within utilities themselves and use `Error` suffix e.g. `MetricUnitError`. | +| **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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | +| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | +| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 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 index 7d767b07dec..f91c58fe45f 100644 --- a/docs/contributing/getting_started.md +++ b/docs/contributing/getting_started.md @@ -37,35 +37,6 @@ Whether you're new contributor or a pro, we compiled a list of the common contri | [Technical debt](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=tech-debt%2Ctriage&projects=&template=tech_debt.yml&title=Tech+debt%3A+TITLE){target="_blank" rel="nofollow"} | Suggest areas to address technical debt that could make maintenance easier or provide customer value faster. Generally used by maintainers and contributors. | | [Governance](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=internal%2Ctriage&projects=&template=maintenance.yml&title=Maintenance%3A+TITLE){target="_blank" rel="nofollow"} | Ideas to improve to our governance processes, automation, and anything internal. Typically used by maintainers and regular contributors. | -## Conventions - -### General terminology and practices - -| 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 [Ruff](https://beta.ruff.rs/docs/) to enforce beyond good practices [PEP8](https://pep8.org/). We use type annotations and enforce static type checking at CI (mypy). | -| **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](https://docs.powertools.aws.dev/lambda/python/#tenets). | -| **Exceptions** | Specific exceptions live within utilities themselves and use `Error` suffix e.g. `MetricUnitError`. | -| **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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | -| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | -| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | -| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | - -**NOTE**: Functional 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 the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), [looking at any 'help wanted' issues is a great place to start](https://github.com/orgs/aws-powertools/projects/3/views/5?query=is%3Aopen+sort%3Aupdated-desc). diff --git a/mkdocs.yml b/mkdocs.yml index d32ed214439..cd3f5c7b93f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,6 +44,7 @@ nav: - contributing/index.md - Development environment: contributing/setup.md - Your first contribution: contributing/getting_started.md + - Conventions: contributing/conventions.md - Testing: - Unit tests: contributing/testing/unit_tests.md - Functional tests: contributing/testing/functional_tests.md From 7c595988ebe03db110ecbb950ff488765e9266d0 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Wed, 20 Sep 2023 11:57:35 -0400 Subject: [PATCH 07/14] docs: remove todo style Signed-off-by: heitorlessa --- docs/contributing/setup.md | 34 +++++++--------------------------- 1 file changed, 7 insertions(+), 27 deletions(-) diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index 3e84cf3e41f..50533fad4b6 100644 --- a/docs/contributing/setup.md +++ b/docs/contributing/setup.md @@ -24,16 +24,16 @@ graph LR Unless you're using the pre-configured Cloud environment, you'll need the following installed: -* [x] [GitHub account](https://github.com/join){target="_blank" rel="nofollow"}. You'll need to be able to fork, clone, and contribute via pull request. -* [x] [Python 3.8+](https://www.python.org/downloads/){target="_blank" rel="nofollow"}. Pick any version supported in [AWS Lambda runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). -* [x] [Docker](https://docs.docker.com/engine/install/){target="_blank" rel="nofollow"}. We use it to run documentation linters and non-Python tooling. -* [x] [Fork the repository](https://github.com/aws-powertools/powertools-lambda-python/fork). You'll work against your fork of this repository. +* [GitHub account](https://github.com/join){target="_blank" rel="nofollow"}. You'll need to be able to fork, clone, and contribute via pull request. +* [Python 3.8+](https://www.python.org/downloads/){target="_blank" rel="nofollow"}. Pick any version supported in [AWS Lambda runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). +* [Docker](https://docs.docker.com/engine/install/){target="_blank" rel="nofollow"}. We use it to run documentation linters and non-Python tooling. +* [Fork the repository](https://github.com/aws-powertools/powertools-lambda-python/fork). You'll work against your fork of this repository. ??? note "Additional requirements if running end-to-end tests" - * [x] [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites){target="_blank"} - * [x] [AWS Account bootstrapped with CDK](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html){target="_blank"} - * [x] [AWS CLI installed and configured](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + * [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites){target="_blank"} + * [AWS Account bootstrapped with CDK](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html){target="_blank"} + * [AWS CLI installed and configured](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) ## Cloud environment @@ -65,23 +65,3 @@ You might find useful to run both the documentation website and the API referenc * **Docs website**: `make docs-local` * If you prefer using Docker: `make docs-local-docker` * **API reference**: `make docs-api-local` - -## 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: - -1. You are working against the latest source on the **develop** branch. -2. You check existing [open, and recently merged](https://github.com/aws-powertools/powertools-lambda-python/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. -3. You open an [issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose){target="_blank" rel="nofollow"} before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful. -4. 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. Run all code quality, tests, and baseline checks: `make pr` -2. Commit to your fork using clear commit messages. Don't worry about typos, we will squash all commits during merge. -3. Send us a pull request with a [conventional semantic title](https://github.com/aws-powertools/powertools-lambda-python/pull/67). We prepared a set of questions you can answer in GitHub User Interface to make reviewing easier. -4. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. From 80fcf7e495a2a4076b594fbf39222a6578e30b75 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Wed, 20 Sep 2023 17:50:22 -0400 Subject: [PATCH 08/14] docs: suggest ideas where to find contributions; move sending PR Signed-off-by: heitorlessa --- docs/contributing/getting_started.md | 36 +++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/contributing/getting_started.md b/docs/contributing/getting_started.md index f91c58fe45f..6deee85ea7f 100644 --- a/docs/contributing/getting_started.md +++ b/docs/contributing/getting_started.md @@ -39,7 +39,41 @@ Whether you're new contributor or a pro, we compiled a list of the common contri ## Finding contributions to work on -Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), [looking at any 'help wanted' issues is a great place to start](https://github.com/orgs/aws-powertools/projects/3/views/5?query=is%3Aopen+sort%3Aupdated-desc). +[Besides suggesting ideas](#types-of-contributions) you think it'll improve everyone's experience, these are the most common places to find work: + +| Area | Description | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Help wanted issues](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22+){target="_blank" rel="nofollow"} | These are triaged areas that we'd appreciate any level of contribution - from opinions to actual implementation. | +| [Missing customer feedback issues](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aneed-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://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3ARFC){target="_blank" rel="nofollow"} | These are feature requests that initially look good but need a RFC to enrich the discussion by validating user-experience, tradeoffs, and highlight use cases. | +| [Backlog items](https://github.com/orgs/aws-powertools/projects/3/views/3?query=is%3Aopen+sort%3Aupdated-desc){target="_blank" rel="nofollow"} | We use GitHub projects to surface what we're working on, needs triage, etc. This view shows items we already triaged but don't have the bandwidth to tackle them just yet. | +| [Documentation](https://docs.powertools.aws.dev/lambda/python/latest/){target="_blank"} | Documentation can always be improved. Look for areas that a better example, or a diagram, or more context helps everyone - keep in mind a diverse audience and English as a second language folks. | +| [Participate in discussions](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"} | There's always a discussion that could benefit others in the form of documentation, blog post, etc. | +| Build a sample application | Using Powertools for AWS Lambda in different contexts will give you insights on what could be made easier, which documentation could be enriched, and more. | + +!!! question "Still couldn't find anything that match your skill set?" + Please reach out on Discord, specially if you'd like to get mentoring for a task you'd like to take but feel you aren't ready yet :) + +## 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 **develop** branch. +* [ ] You check existing [open, and recently merged](https://github.com/aws-powertools/powertools-lambda-python/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 open an [issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose){target="_blank" rel="nofollow"} before you begin any implementation. We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful. +* [ ] Create a new branch named after the change you are contributing _e.g._ `feat/logger-debug-sampling` + +**Ready?** + +These are the steps to send a pull request: + +1. Run all formatting, linting, tests, documentation and baseline checks: `make pr` +2. Commit to your fork using clear commit messages. Don't worry about typos or format, we squash all commits during merge. +3. Send us a pull request with a [conventional semantic title](https://github.com/aws-powertools/powertools-lambda-python/pull/67). +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 From 902f518ff57b05ab6c366d1ee3ee257d1f9f46ef Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Wed, 20 Sep 2023 17:58:30 -0400 Subject: [PATCH 09/14] docs: add a disclaimer this will keep improving Signed-off-by: heitorlessa --- docs/contributing/getting_started.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/contributing/getting_started.md b/docs/contributing/getting_started.md index 6deee85ea7f..67c129f7f1e 100644 --- a/docs/contributing/getting_started.md +++ b/docs/contributing/getting_started.md @@ -7,13 +7,7 @@ description: All you need to know for your first contribution to Powertools for Thank you for your interest in contributing to our project - we couldn't be more excited! -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 contribution. - -**TODO** - -* [x] Types of contributions (slide as example); make a table -* [ ] How contributions are licensed etc - confirm whether we can remove CLAs mention -* [ ] Refer to licensing within sending a PR section +!!! note "This is a living document that we will keep iterating based on everyone's feedback." ## Types of contributions @@ -52,7 +46,7 @@ Whether you're new contributor or a pro, we compiled a list of the common contri | Build a sample application | Using Powertools for AWS Lambda in different contexts will give you insights on what could be made easier, which documentation could be enriched, and more. | !!! question "Still couldn't find anything that match your skill set?" - Please reach out on Discord, specially if you'd like to get mentoring for a task you'd like to take but feel you aren't ready yet :) + Please reach out on [Discord](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"}, specially if you'd like to get mentoring for a task you'd like to take but you don't feel ready yet :) ## Sending a pull request From cec94fc53b7dde0edd8f984249760b99eaf9333b Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Wed, 20 Sep 2023 18:03:17 -0400 Subject: [PATCH 10/14] docs(setup): last cleanups Signed-off-by: heitorlessa --- docs/contributing/getting_started.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/contributing/getting_started.md b/docs/contributing/getting_started.md index 67c129f7f1e..583937d39a7 100644 --- a/docs/contributing/getting_started.md +++ b/docs/contributing/getting_started.md @@ -48,6 +48,8 @@ Whether you're new contributor or a pro, we compiled a list of the common contri !!! question "Still couldn't find anything that match your skill set?" Please reach out on [Discord](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"}, specially if you'd like to get mentoring for a task you'd like to take but you don't feel ready yet :) + 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'}" @@ -78,7 +80,7 @@ For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of ## Security issue notifications -If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. +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. ## Troubleshooting From 1cf9fa0bdb5f308e06dfb731a0679f5e1523f00e Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Wed, 20 Sep 2023 18:12:39 -0400 Subject: [PATCH 11/14] docs: visualize key steps Signed-off-by: heitorlessa --- docs/contributing/getting_started.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/contributing/getting_started.md b/docs/contributing/getting_started.md index 583937d39a7..abf445c1f9d 100644 --- a/docs/contributing/getting_started.md +++ b/docs/contributing/getting_started.md @@ -7,7 +7,13 @@ description: All you need to know for your first contribution to Powertools for Thank you for your interest in contributing to our project - we couldn't be more excited! -!!! note "This is a living document that we will keep iterating based on everyone's feedback." +
+```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 From 1225b80e6b8321fa2b809822ed54dfd991879824 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 25 Sep 2023 10:26:09 +0200 Subject: [PATCH 12/14] docs: add roadmap item Signed-off-by: heitorlessa --- docs/contributing/getting_started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing/getting_started.md b/docs/contributing/getting_started.md index abf445c1f9d..3cdcc6b1ddc 100644 --- a/docs/contributing/getting_started.md +++ b/docs/contributing/getting_started.md @@ -49,6 +49,7 @@ Whether you're new contributor or a pro, we compiled a list of the common contri | [Backlog items](https://github.com/orgs/aws-powertools/projects/3/views/3?query=is%3Aopen+sort%3Aupdated-desc){target="_blank" rel="nofollow"} | We use GitHub projects to surface what we're working on, needs triage, etc. This view shows items we already triaged but don't have the bandwidth to tackle them just yet. | | [Documentation](https://docs.powertools.aws.dev/lambda/python/latest/){target="_blank"} | Documentation can always be improved. Look for areas that a better example, or a diagram, or more context helps everyone - keep in mind a diverse audience and English as a second language folks. | | [Participate in discussions](https://discord.gg/B8zZKbbyET){target="_blank" rel="nofollow"} | There's always a discussion that could benefit others in the form of documentation, blog post, etc. | +| [Roadmap](../roadmap.md){target="_blank"} | Some roadmap items need a RFC to discuss design options, or gather customers use case before we can prioritize it. | | Build a sample application | Using Powertools for AWS Lambda in different contexts will give you insights on what could be made easier, which documentation could be enriched, and more. | !!! question "Still couldn't find anything that match your skill set?" From 03984230239c99501935fdbbbe4e45f299dd36f2 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 25 Sep 2023 11:12:36 +0200 Subject: [PATCH 13/14] docs: update roadmap end of sept Signed-off-by: heitorlessa --- docs/roadmap.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index c2de6829fb4..e42fae21c97 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -36,8 +36,9 @@ Data Masking will be a new utility to mask/unmask sensitive data using encryptio **Major updates** - [x] [RFC to agree on design and MVP](https://github.com/aws-powertools/powertools-lambda-python/issues/1858) -- [ ] [POC with AWS KMS as the default provider](https://github.com/aws-powertools/powertools-lambda-python/pull/2197) -- [ ] Documentation to guide customers how to bring their own provider (e.g., `ItsDangerous`) +- [x] [POC with AWS KMS as the default provider](https://github.com/aws-powertools/powertools-lambda-python/pull/2197) +- [ ] User-guide documentation and include when not to use it (e.g., when to use SNS data policy, CloudWatch Logs data policy) +- [ ] Decide whether to use Encryption SDK to bring their own provider or a simply a contract (e.g., `ItsDangerous`) ### Revamp Event Handler @@ -49,8 +50,8 @@ Based on customers feedback, we want to provide middleware authoring support for - [x] [Agree on experience for middleware support](https://github.com/aws-powertools/powertools-lambda-python/issues/953#issuecomment-1450223155) - [x] [RFC to outline initial thoughts on OpenAPI integration](https://github.com/aws-powertools/powertools-lambda-python/issues/2421) -- [ ] MVP for REST middleware -- [ ] MVP for OpenAPI and SwaggerUI +- [x] [MVP for REST middleware](./core/event_handler/api_gateway.md#middleware) +- [ ] [MVP for OpenAPI and SwaggerUI](https://github.com/aws-powertools/powertools-lambda-python/pull/3109) - [ ] [MVP for AppSync Batch invoke and partial failure support](https://github.com/aws-powertools/powertools-lambda-python/pull/1998) ### Lambda Layer in release notes @@ -112,10 +113,10 @@ We want to investigate security and scaling requirements for these special regio **Major updates** -- [ ] Gather agencies and customers name to prioritize it -- [ ] Investigate security requirements for special regions -- [ ] Update CDK Layer construct to include regions +- [x] Gather agencies and customers name to prioritize it +- [x] Investigate security requirements for special regions - [ ] Create additional infrastructure for special regions +- [ ] Update CDK Layer construct to include regions ### V3 From bb964db1f0004bbad4844deea1803d7d27d2c4af Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 25 Sep 2023 11:18:20 +0200 Subject: [PATCH 14/14] docs: hide final structure --- docs/contributing/documentation/api_guide.md | 8 - docs/contributing/documentation/tutorials.md | 8 - docs/contributing/documentation/user_guide.md | 8 - docs/contributing/index.md | 172 ------------------ docs/contributing/testing/e2e_tests.md | 18 -- docs/contributing/testing/functional_tests.md | 18 -- docs/contributing/testing/unit_tests.md | 18 -- .../tracks/casual_regular_contributor.md | 8 - docs/contributing/tracks/customer_advocate.md | 8 - docs/contributing/tracks/overview.md | 8 - mkdocs.yml | 28 +-- 11 files changed, 14 insertions(+), 288 deletions(-) delete mode 100644 docs/contributing/documentation/api_guide.md delete mode 100644 docs/contributing/documentation/tutorials.md delete mode 100644 docs/contributing/documentation/user_guide.md delete mode 100644 docs/contributing/index.md delete mode 100644 docs/contributing/testing/e2e_tests.md delete mode 100644 docs/contributing/testing/functional_tests.md delete mode 100644 docs/contributing/testing/unit_tests.md delete mode 100644 docs/contributing/tracks/casual_regular_contributor.md delete mode 100644 docs/contributing/tracks/customer_advocate.md delete mode 100644 docs/contributing/tracks/overview.md diff --git a/docs/contributing/documentation/api_guide.md b/docs/contributing/documentation/api_guide.md deleted file mode 100644 index 7e7e10085bf..00000000000 --- a/docs/contributing/documentation/api_guide.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Writing API guide documentation -description: Contributing API documentation to Powertools for AWS Lambda (Python) ---- - -## TBW - -Something great will come. diff --git a/docs/contributing/documentation/tutorials.md b/docs/contributing/documentation/tutorials.md deleted file mode 100644 index 0cdaa2978d5..00000000000 --- a/docs/contributing/documentation/tutorials.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Writing tutorials -description: Contributing tutorials to Powertools for AWS Lambda (Python) ---- - -## TBW - -Something great will come. diff --git a/docs/contributing/documentation/user_guide.md b/docs/contributing/documentation/user_guide.md deleted file mode 100644 index 41c5653d264..00000000000 --- a/docs/contributing/documentation/user_guide.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Writing user guide documentation -description: Contributing documentation to Powertools for AWS Lambda (Python) ---- - -## TBW - -Something great will come. diff --git a/docs/contributing/index.md b/docs/contributing/index.md deleted file mode 100644 index cb7b9738109..00000000000 --- a/docs/contributing/index.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Contributing -description: Contributing to Powertools for AWS Lambda (Python) ---- - -## Contributing Guidelines - - -Thank you for your interest in contributing to our project. Whether it's a [bug report](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=bug%2Ctriage&projects=&template=bug_report.yml&title=Bug%3A+TITLE), [new feature](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2Ctriage&projects=&template=feature_request.yml&title=Feature+request%3A+TITLE), [correction](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose), or [additional documentation](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=documentation%2Ctriage&projects=&template=documentation_improvements.yml&title=Docs%3A+TITLE), we greatly value feedback and contributions from our community. - - -Please read through this document before submitting any issues or pull requests to ensure we have all the necessary -information to effectively respond to your bug report or contribution. - -## Reporting Bugs/Feature Requests - -We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements. - - -[When filing an issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose), please check [existing open](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc), or [recently closed](https://github.com/aws-powertools/powertools-lambda-python/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed), issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. - - -## Contributing via Pull Requests - -Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: - -1. You are working against the latest source on the **develop** branch. -2. You check existing open, and recently merged pull requests to make sure someone else hasn't addressed the problem already. -3. You open an [issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new/choose) 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. - -```mermaid -timeline - title Code integration journey (CI) - Project setup
(make dev) : Code checkout - : Virtual environment - : Dependencies - : Git pre-commit hooks - : Local branch - : Local changes - : Local tests - - Pre-commit checks
(git commit) : Merge conflict check - : Trailing whitespaces - : TOML checks - : Code linting (standards) - : Markdown linting - : CloudFormation linting - : GitHub Actions linting - : Terraform linting - : Secrets linting - - Pre-Pull Request
(make pr) : Code linting - : Docs linting - : Static typing analysis - : Tests (unit|functional|perf) - : Security baseline - : Complexity baseline - : +pre-commit checks - - Pull Request
(CI checks) : Semantic PR title check - : Related issue check - : Acknowledgment check - : Code coverage diff - : Contribution size check - : Contribution category check - : Dependency vulnerability check - : GitHub Actions security check - : +pre-pull request checks - - After merge
(CI checks) : End-to-end tests - : Longer SAST check - : Security posture check (scorecard) - : GitHub Actions security check - : Rebuild Changelog - : Deploy staging docs - : Update draft release -``` - -### Dev setup - -[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/from-referrer/) - -Firstly, [fork the repository](https://github.com/aws-powertools/powertools-lambda-python/fork). - -To setup your development environment, we recommend using our pre-configured Cloud environment: . Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly. - -Alternatively, you can use `make dev` within your local virtual environment. - -To send us a pull request, please follow these steps: - -1. Create a new branch to focus on the specific change you are contributing e.g. `improv/logger-debug-sampling` -2. Run all tests, and code baseline checks: `make pr` - - Git hooks will run linting and formatting while `make pr` run deep checks that also run in the CI process -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-python/pull/67), and answering any default questions in the pull request interface. -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/). - -### Local documentation - -You might find useful to run both the documentation website and the API reference locally while contributing: - -- **API reference**: `make docs-api-local` -- **Docs website**: `make docs-local` - - If you prefer using Docker: `make docs-local-docker` - -## Conventions - -### General terminology and practices - -| 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 [Ruff](https://beta.ruff.rs/docs/) to enforce beyond good practices [PEP8](https://pep8.org/). We use type annotations and enforce static type checking at CI (mypy). | -| **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](https://docs.powertools.aws.dev/lambda/python/#tenets). | -| **Exceptions** | Specific exceptions live within utilities themselves and use `Error` suffix e.g. `MetricUnitError`. | -| **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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | -| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | -| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | -| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | - -**NOTE**: Functional 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 the default GitHub issue labels (enhancement/bug/help wanted/invalid/question/documentation), [looking at any 'help wanted' issues is a great place to start](https://github.com/orgs/aws-powertools/projects/3/views/5?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). -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 ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. - -## Troubleshooting - -### API reference documentation - -When you are working on the codebase and you use the local API reference documentation to preview your changes, you might see the following message: `Module aws_lambda_powertools not found`. - -This happens when: - -- You did not install the local dev environment yet - - You can install dev deps with `make dev` command -- The code in the repository is raising an exception while the `pdoc` is scanning the codebase - - Unfortunately, this exception is not shown to you, but if you run, `poetry run pdoc --pdf aws_lambda_powertools`, the exception is shown and you can prevent the exception from being raised - - Once resolved the documentation should load correctly again - -## Licensing - -See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. - -We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. diff --git a/docs/contributing/testing/e2e_tests.md b/docs/contributing/testing/e2e_tests.md deleted file mode 100644 index a7a519de101..00000000000 --- a/docs/contributing/testing/e2e_tests.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Writing unit tests -description: Contributing unit tests to Powertools for AWS Lambda (Python) ---- - -### 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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | -| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | -| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | -| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | - -**NOTE**: Functional 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. diff --git a/docs/contributing/testing/functional_tests.md b/docs/contributing/testing/functional_tests.md deleted file mode 100644 index 0365fe7d164..00000000000 --- a/docs/contributing/testing/functional_tests.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Writing functional tests -description: Contributing functional tests to Powertools for AWS Lambda (Python) ---- - -### 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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | -| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | -| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | -| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | - -**NOTE**: Functional 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. diff --git a/docs/contributing/testing/unit_tests.md b/docs/contributing/testing/unit_tests.md deleted file mode 100644 index a7a519de101..00000000000 --- a/docs/contributing/testing/unit_tests.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Writing unit tests -description: Contributing unit tests to Powertools for AWS Lambda (Python) ---- - -### 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. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) | -| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) | -| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) | -| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | 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 our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) | - -**NOTE**: Functional 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. diff --git a/docs/contributing/tracks/casual_regular_contributor.md b/docs/contributing/tracks/casual_regular_contributor.md deleted file mode 100644 index 9f564954e40..00000000000 --- a/docs/contributing/tracks/casual_regular_contributor.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Becoming a regular contributor -description: From casual contributions to regular contributor in Powertools for AWS Lambda (Python) ---- - -## TBW - -Something great will come. diff --git a/docs/contributing/tracks/customer_advocate.md b/docs/contributing/tracks/customer_advocate.md deleted file mode 100644 index 857d87ab55a..00000000000 --- a/docs/contributing/tracks/customer_advocate.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Becoming an advocate -description: From customer to Powertools for AWS Lambda (Python) advocate ---- - -## TBW - -Something great will come. diff --git a/docs/contributing/tracks/overview.md b/docs/contributing/tracks/overview.md deleted file mode 100644 index ab41f3dd61a..00000000000 --- a/docs/contributing/tracks/overview.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Tracks overview -description: Overview of different tracks when contributing to Powertools for AWS Lambda (Python) advocate ---- - -## TBW - -Something great will come. diff --git a/mkdocs.yml b/mkdocs.yml index cd3f5c7b93f..0a844fd392f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,23 +41,23 @@ nav: - Roadmap: roadmap.md - Maintainers: maintainers.md - Contributing: - - contributing/index.md + # - contributing/index.md - Development environment: contributing/setup.md - Your first contribution: contributing/getting_started.md - Conventions: contributing/conventions.md - - Testing: - - Unit tests: contributing/testing/unit_tests.md - - Functional tests: contributing/testing/functional_tests.md - - End-to-end tests: contributing/testing/e2e_tests.md - - Documentation: - - User guide: contributing/documentation/user_guide.md - - API guide: contributing/documentation/api_guide.md - - Tutorials: contributing/documentation/tutorials.md - - Request For Comments (RFC): contributing/documentation/rfc.md - - Tracks: - - Overview: contributing/tracks/overview.md - - Casual to regular contributor: contributing/tracks/casual_regular_contributor.md - - Customer to advocate: contributing/tracks/customer_advocate.md + # - Testing: + # - Unit tests: contributing/testing/unit_tests.md + # - Functional tests: contributing/testing/functional_tests.md + # - End-to-end tests: contributing/testing/e2e_tests.md + # - Documentation: + # - User guide: contributing/documentation/user_guide.md + # - API guide: contributing/documentation/api_guide.md + # - Tutorials: contributing/documentation/tutorials.md + # - Request For Comments (RFC): contributing/documentation/rfc.md + # - Tracks: + # - Overview: contributing/tracks/overview.md + # - Casual to regular contributor: contributing/tracks/casual_regular_contributor.md + # - Customer to advocate: contributing/tracks/customer_advocate.md theme: name: material