From 7147a6879b9cda06afd7c735419f97bc0c69c193 Mon Sep 17 00:00:00 2001 From: Philipp Page Date: Fri, 11 Apr 2025 11:05:41 +0200 Subject: [PATCH 1/6] Add llms.txt. Update Roadmap. --- .gitignore | 3 ++- docs/requirements.in | 1 + docs/requirements.txt | 38 +++++++++++++++++++++++++++++++++++++- docs/roadmap.md | 18 ++++++++++-------- mkdocs.yml | 23 +++++++++++++++++++++++ 5 files changed, 73 insertions(+), 10 deletions(-) diff --git a/.gitignore b/.gitignore index 64f0be6a3..983008b7f 100644 --- a/.gitignore +++ b/.gitignore @@ -99,6 +99,7 @@ Desktop.ini docs/node_modules docs/.cache +.cache docs/public /example/.aws-sam/ /example/HelloWorldFunction/.aws-sam/ @@ -112,4 +113,4 @@ build/ .terraform* terraform.tfstate* -powertools-idempotency/dynamodb-local-metadata.json \ No newline at end of file +powertools-idempotency/dynamodb-local-metadata.json diff --git a/docs/requirements.in b/docs/requirements.in index 0457fb24e..e8acc7112 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,2 +1,3 @@ mkdocs-git-revision-date-plugin==0.3.2 mkdocs-macros-plugin==1.3.7 +mkdocs-llmstxt==0.2.0 diff --git a/docs/requirements.txt b/docs/requirements.txt index 5efd15b23..aa8303c94 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,6 +4,12 @@ # # pip-compile --generate-hashes --output-file=requirements.txt requirements.in # +beautifulsoup4==4.13.3 \ + --hash=sha256:1bd32405dacc920b42b83ba01644747ed77456a65760e285fbc47633ceddaf8b \ + --hash=sha256:99045d7d3f08f91f0d656bc9b7efbae189426cd913d830294a15eefa0ea4df16 + # via + # markdownify + # mkdocs-llmstxt click==8.1.8 \ --hash=sha256:63c132bbbed01578a06712a2d1f497bb62d9c1c0d329b7903a866228027263b2 \ --hash=sha256:ed53c9d8990d83c2a27deae68e4ee337473f6330c040a31d4225c9574d16096a @@ -37,6 +43,14 @@ markdown==3.7 \ --hash=sha256:2ae2471477cfd02dbbf038d5d9bc226d40def84b4fe2986e49b59b6b472bbed2 \ --hash=sha256:7eb6df5690b81a1d7942992c97fad2938e956e79df20cbc6186e9c3a77b1c803 # via mkdocs +markdown-it-py==3.0.0 \ + --hash=sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1 \ + --hash=sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb + # via mdformat +markdownify==1.1.0 \ + --hash=sha256:32a5a08e9af02c8a6528942224c91b933b4bd2c7d078f9012943776fc313eeef \ + --hash=sha256:449c0bbbf1401c5112379619524f33b63490a8fa479456d41de9dc9e37560ebd + # via mkdocs-llmstxt markupsafe==3.0.2 \ --hash=sha256:0bff5e0ae4ef2e1ae4fdf2dfd5b76c75e5c2fa4132d05fc1b0dabcd20c7e28c4 \ --hash=sha256:0f4ca02bea9a23221c0182836703cbf8930c5e9454bacce27e767509fa286a30 \ @@ -102,6 +116,14 @@ markupsafe==3.0.2 \ # via # jinja2 # mkdocs +mdformat==0.7.22 \ + --hash=sha256:61122637c9e1d9be1329054f3fa216559f0d1f722b7919b060a8c2a4ae1850e5 \ + --hash=sha256:eef84fa8f233d3162734683c2a8a6222227a229b9206872e6139658d99acb1ea + # via mkdocs-llmstxt +mdurl==0.1.2 \ + --hash=sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8 \ + --hash=sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba + # via markdown-it-py mergedeep==1.3.4 \ --hash=sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8 \ --hash=sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307 @@ -121,6 +143,10 @@ mkdocs-get-deps==0.2.0 \ mkdocs-git-revision-date-plugin==0.3.2 \ --hash=sha256:2e67956cb01823dd2418e2833f3623dee8604cdf223bddd005fe36226a56f6ef # via -r requirements.in +mkdocs-llmstxt==0.2.0 \ + --hash=sha256:104f10b8101167d6baf7761942b4743869be3d8f8a8d909f4e9e0b63307f709e \ + --hash=sha256:907de892e0c8be74002e8b4d553820c2b5bbcf03cc303b95c8bca48fb49c1a29 + # via -r requirements.in mkdocs-macros-plugin==1.3.7 \ --hash=sha256:02432033a5b77fb247d6ec7924e72fc4ceec264165b1644ab8d0dc159c22ce59 \ --hash=sha256:17c7fd1a49b94defcdb502fd453d17a1e730f8836523379d21292eb2be4cb523 @@ -213,11 +239,17 @@ pyyaml-env-tag==0.1 \ six==1.17.0 \ --hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274 \ --hash=sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81 - # via python-dateutil + # via + # markdownify + # python-dateutil smmap==5.0.2 \ --hash=sha256:26ea65a03958fa0c8a1c7e8c7a58fdc77221b8910f6be2131affade476898ad5 \ --hash=sha256:b30115f0def7d7531d22a0fb6502488d879e75b260a9db4d0819cfb25403af5e # via gitdb +soupsieve==2.6 \ + --hash=sha256:e2e68417777af359ec65daac1057404a3c8a5455bb8abc36f1a9866ab1a51abb \ + --hash=sha256:e72c4ff06e4fb6e4b5a9f0f55fe6e81514581fca1515028625d0f299c602ccc9 + # via beautifulsoup4 super-collections==0.5.3 \ --hash=sha256:907d35b25dc4070910e8254bf2f5c928348af1cf8a1f1e8259e06c666e902cff \ --hash=sha256:94c1ec96c0a0d5e8e7d389ed8cde6882ac246940507c5e6b86e91945c2968d46 @@ -226,6 +258,10 @@ termcolor==2.5.0 \ --hash=sha256:37b17b5fc1e604945c2642c872a3764b5d547a48009871aea3edd3afa180afb8 \ --hash=sha256:998d8d27da6d48442e8e1f016119076b690d962507531df4890fcd2db2ef8a6f # via mkdocs-macros-plugin +typing-extensions==4.13.2 \ + --hash=sha256:a439e7c04b49fec3e5d3e2beaa21755cadbbdc391694e28ccdd36ca4a1408f8c \ + --hash=sha256:e6c81219bd689f51865d9e372991c540bda33a0379d5573cddb9a3a23f7caaef + # via beautifulsoup4 watchdog==6.0.0 \ --hash=sha256:07df1fdd701c5d4c8e55ef6cf55b8f0120fe1aef7ef39a1c6fc6bc2e606d517a \ --hash=sha256:20ffe5b202af80ab4266dcd3e91aae72bf2da48c0d33bdb15c66658e685e94e2 \ diff --git a/docs/roadmap.md b/docs/roadmap.md index 975c1f8c5..4a86f1437 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -18,8 +18,8 @@ Security and operational excellence take precedence above all else. This means b Our top priority is to establish the processes and infrastructure needed for a fully automated and secure end-to-end release process of new versions to Maven Central. - [ ] Implement GitHub workflows and create infrastructure to release to Maven Central -- [ ] Implement end-to-end tests -- [ ] Implement [OpenSSF Scorecard](https://openssf.org/projects/scorecard/){target="\_blank"} +- [x] [Implement end-to-end tests](https://github.com/aws-powertools/powertools-lambda-java/issues/1815){target="\_blank"} +- [x] Implement [OpenSSF Scorecard](https://openssf.org/projects/scorecard/){target="\_blank"} #### `v2` Release: Consistency and Ecosystem (p1) @@ -28,26 +28,28 @@ As part of a new major version `v2` release, we prioritize the Java project's co ##### Core Utilities - [ ] [Review public interfaces and reduce public API surface area](https://github.com/aws-powertools/powertools-lambda-java/issues/1283){target="\_blank"} -- [ ] [Release Logging `v2` module](https://github.com/aws-powertools/powertools-lambda-java/issues/965){target="\_blank"} -- [ ] [Support high resolution metrics](https://github.com/aws-powertools/powertools-lambda-java/issues/1041){target="\_blank"} +- [x] [Release Logging `v2` module](https://github.com/aws-powertools/powertools-lambda-java/issues/965){target="\_blank"} allowing customers to choose the logging framework and adding support for logging deeply nested objects as JSON +- [x] [Support high resolution metrics](https://github.com/aws-powertools/powertools-lambda-java/issues/1041){target="\_blank"} ##### Ecosystem -- [ ] [Add GraalVM support](https://github.com/aws-powertools/powertools-lambda-java/issues/764){target="\_blank"} +- [x] [Add GraalVM support for core utilities](https://github.com/aws-powertools/powertools-lambda-java/issues/764){target="\_blank"} - [ ] [Implement priming using CRaC to improve AWS Snapstart support](https://github.com/aws-powertools/powertools-lambda-java/issues/1588){target="\_blank"} - [ ] [Evaluate integration with popular Java frameworks such as Micronaut, Spring Cloud Function, or Quarkus](https://github.com/aws-powertools/powertools-lambda-java/issues/1701){target="\_blank"} ##### Other -- [ ] [Validation module integration with HTTP requests](https://github.com/aws-powertools/powertools-lambda-java/issues/1298){target="\_blank"} -- [ ] [Support validation module from within the batch module](https://github.com/aws-powertools/powertools-lambda-java/issues/1496){target="\_blank"} -- [ ] Documentation: Review and improve documentation to be consistent with other runtimes +- [x] [Validation module integration with HTTP requests](https://github.com/aws-powertools/powertools-lambda-java/issues/1298){target="\_blank"} +- [x] [Support validation module from within the batch module](https://github.com/aws-powertools/powertools-lambda-java/issues/1496){target="\_blank"} +- [x] [Add support for parallel processing in Batch Processing utility](https://github.com/aws-powertools/powertools-lambda-java/issues/1540){target="\_blank"} +- [ ] [Documentation: Review and improve documentation to be consistent with other runtimes](https://github.com/aws-powertools/powertools-lambda-java/issues/1352){target="\_blank"} #### Feature Parity (p2) If priorities `p0` and `p1` are addressed, we will also focus on feature parity of non-core utilities. This allows customers to achieve better standardization of their development processes across different Powertools runtimes. - [ ] [Re-evaluate if there is a need for adding a lightweight customer Powertools event handler](https://github.com/aws-powertools/powertools-lambda-java/issues/1103){target="\_blank"} +- [ ] [Add comprehensive GraalVM support for all utilities](){target="\_blank"} - [ ] [Add Feature Flags module](https://github.com/aws-powertools/powertools-lambda-java/issues/1086){target="\_blank"} - [ ] [Add S3 Streaming module](https://github.com/aws-powertools/powertools-lambda-java/issues/1085){target="\_blank"} - [ ] Add support for Data Masking during JSON serialization diff --git a/mkdocs.yml b/mkdocs.yml index 76750d409..a7570e08a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,6 +83,29 @@ plugins: - git-revision-date - search - macros + - llmstxt: + markdown_description: Powertools for AWS Lambda (Java) is a developer toolkit to implement Serverless best practices and increase developer velocity. It provides a suite of utilities for AWS Lambda Functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier. + full_output: llms-full.txt + sections: + Project Overview: + - index.md + - changelog.md + - FAQs.md + - roadmap.md + Core Utilities: + - core/logging.md + - core/metrics.md + - core/tracing.md + Utilities: + - utilities/idempotency.md + - utilities/parameters.md + - utilities/large_messages.md + - utilities/batch.md + - utilities/validation.md + - utilities/custom_resources.md + - utilities/serialization.md + Processes: + - processes/maintainers.md extra_css: - stylesheets/extra.css From 4c384c71e88c022041c7d099cf4448d0d470a8b1 Mon Sep 17 00:00:00 2001 From: Philipp Page Date: Fri, 11 Apr 2025 11:41:20 +0200 Subject: [PATCH 2/6] Remove new label from Workshop link. --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index a7570e08a..b743a4be5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,7 +5,7 @@ site_url: https://docs.powertools.aws.dev/lambda-java/ nav: - Homepage: index.md - Changelog: changelog.md - - Workshop 🆕: https://s12d.com/powertools-for-aws-lambda-workshop" target="_blank + - Workshop: https://s12d.com/powertools-for-aws-lambda-workshop" target="_blank - FAQs: FAQs.md - Roadmap: roadmap.md - Core utilities: From 8f51915a2be687872f9dd5078d27fcad963e665c Mon Sep 17 00:00:00 2001 From: Philipp Page Date: Tue, 22 Apr 2025 12:59:47 +0200 Subject: [PATCH 3/6] Enable privacy plugin and llms.txt to navigation bar resources. --- mkdocs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index b743a4be5..117d6a8b8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,9 @@ nav: - utilities/sqs_batch.md - Processes: - processes/maintainers.md + - Resources: + - "llms.txt": ./llms.txt + - "llms.txt (full version)": ./llms-full.txt theme: name: material @@ -83,6 +86,7 @@ plugins: - git-revision-date - search - macros + - privacy - llmstxt: markdown_description: Powertools for AWS Lambda (Java) is a developer toolkit to implement Serverless best practices and increase developer velocity. It provides a suite of utilities for AWS Lambda Functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier. full_output: llms-full.txt From ddfc086c41cf98f4db4f20b52cd8977398b18f73 Mon Sep 17 00:00:00 2001 From: Philipp Page Date: Tue, 22 Apr 2025 15:22:41 +0200 Subject: [PATCH 4/6] Add Versioning policy page. --- docs/processes/versioning.md | 60 ++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 61 insertions(+) create mode 100644 docs/processes/versioning.md diff --git a/docs/processes/versioning.md b/docs/processes/versioning.md new file mode 100644 index 000000000..8b12e0fa9 --- /dev/null +++ b/docs/processes/versioning.md @@ -0,0 +1,60 @@ +--- +title: Versioning and maintenance policy +description: Versioning and maintenance policy for Powertools for AWS Lambda (Python) +--- + +### Overview + +This document outlines the maintenance policy for Powertools for AWS Lambda and their underlying dependencies. AWS regularly provides Powertools for AWS Lambda with updates that may contain new features, enhancements, bug fixes, security patches, or documentation updates. Updates may also address changes with dependencies, language runtimes, and operating systems. Powertools for AWS Lambda is published to package managers (e.g. PyPi, NPM, Maven, NuGet), and are available as source code on GitHub. + +We recommend users to stay up-to-date with Powertools for AWS Lambda releases to keep up with the latest features, security updates, and underlying dependencies. Continued use of an unsupported Powertools for AWS Lambda version is not recommended and is done at the user’s discretion. + +!!! info "For brevity, we will interchangeably refer to Powertools for AWS Lambda as "SDK" _(Software Development Toolkit)_." + +### Versioning + +Powertools for AWS Lambda release versions are in the form of X.Y.Z where X represents the major version. Increasing the major version of an SDK indicates that this SDK underwent significant and substantial changes to support new idioms and patterns in the language. Major versions are introduced when public interfaces _(e.g. classes, methods, types, etc.)_, behaviors, or semantics have changed. Applications need to be updated in order for them to work with the newest SDK version. It is important to update major versions carefully and in accordance with the upgrade guidelines provided by AWS. + +### SDK major version lifecycle + +The lifecycle for major Powertools for AWS Lambda versions consists of 5 phases, which are outlined below. + +- **Developer Preview** (Phase 0) - During this phase, SDKs are not supported, should not be used in production environments, and are meant for early access and feedback purposes only. It is possible for future releases to introduce breaking changes. Once AWS identifies a release to be a stable product, it may mark it as a Release Candidate. Release Candidates are ready for GA release unless significant bugs emerge, and will receive full AWS support. +- **General Availability (GA)** (Phase 1) - During this phase, SDKs are fully supported. AWS will provide regular SDK releases that include support for new features, enhancements, as well as bug and security fixes. AWS will support the GA version of an SDK for _at least 24 months_, unless otherwise specified. +- **Maintenance Announcement** (Phase 2) - AWS will make a public announcement at least 6 months before an SDK enters maintenance mode. During this period, the SDK will continue to be fully supported. Typically, maintenance mode is announced at the same time as the next major version is transitioned to GA. +- **Maintenance** (Phase 3) - During the maintenance mode, AWS limits SDK releases to address critical bug fixes and security issues only. An SDK will not receive API updates for new or existing services, or be updated to support new regions. Maintenance mode has a _default duration of 6 months_, unless otherwise specified. +- **End-of-Support** (Phase 4) - When an SDK reaches end-of support, it will no longer receive updates or releases. Previously published releases will continue to be available via public package managers and the code will remain on GitHub. The GitHub repository may be archived. Use of an SDK which has reached end-of-support is done at the user’s discretion. We recommend users upgrade to the new major version. + +!!! note "Please note that the timelines shown below are illustrative and not binding" + +![Maintenance policy timelines](https://docs.aws.amazon.com/images/sdkref/latest/guide/images/maint-policy.png) + +### Dependency lifecycle + +Most AWS SDKs have underlying dependencies, such as language runtimes, AWS Lambda runtime, or third party libraries and frameworks. These dependencies are typically tied to the language community or the vendor who owns that particular component. Each community or vendor publishes their own end-of-support schedule for their product. + +The following terms are used to classify underlying third party dependencies: + +- [**AWS Lambda Runtime**](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html): Examples include `java17`, `nodejs20.x`, `python3.13`, etc. +- **Language Runtime**: Examples include Java 17, Python 3.13, NodeJS 20, .NET Core, etc. +- **Third party Library**: Examples include Jackson Project, AWS X-Ray SDK, AWS Encryption SDK, etc. + +Powertools for AWS Lambda follows the [AWS Lambda Runtime deprecation policy cycle](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html#runtime-support-policy), when it comes to Language Runtime. This means we will stop supporting their respective deprecated Language Runtime _(e.g., `java8`)_ without increasing the major SDK version. + +!!! note "AWS reserves the right to stop support for an underlying dependency without increasing the major SDK version" + +### Communication methods + +Maintenance announcements are communicated in several ways: + +- A pinned GitHub Request For Comments (RFC) issue indicating the campaign for the next major version. The RFC will outline the path to end-of-support, specify campaign timelines, and upgrade guidance. +- AWS SDK documentation, such as API reference documentation, user guides, SDK product marketing pages, and GitHub readme(s) are updated to indicate the campaign timeline and provide guidance on upgrading affected applications. +- Deprecation warnings are added to the SDKs, outlining the path to end-of-support and linking to the upgrade guide. + +To see the list of available major versions of Powertools for AWS Lambda and where they are in their maintenance lifecycle, see the [version support matrix](#version-support-matrix). + +### Version support matrix + +| SDK | Major version | Current Phase | General Availability Date | Notes | +| -------------------------------- | ------------- | -------------------- | ------------------------- | ------------------------------------------------------------------------------------------------- | +| Powertools for AWS Lambda (Java) | 1.x | General Availability | 11/04/2020 | See [Release notes](https://github.com/aws-powertools/powertools-lambda-java/releases/tag/v1.0.0) | diff --git a/mkdocs.yml b/mkdocs.yml index 117d6a8b8..cb856a39a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,7 @@ nav: - utilities/sqs_batch.md - Processes: - processes/maintainers.md + - processes/versioning.md - Resources: - "llms.txt": ./llms.txt - "llms.txt (full version)": ./llms-full.txt From 1088404d60b535c96e658eba739fe77077d7c224 Mon Sep 17 00:00:00 2001 From: Philipp Page Date: Fri, 25 Apr 2025 11:05:13 +0200 Subject: [PATCH 5/6] Update site_url in mkdocs.yml. Fix formatting issues in validation.md. --- docs/utilities/validation.md | 10 ++++++---- mkdocs.yml | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/utilities/validation.md b/docs/utilities/validation.md index 928ffb6c8..23f7f09d5 100644 --- a/docs/utilities/validation.md +++ b/docs/utilities/validation.md @@ -176,7 +176,8 @@ While it is easier to specify a json schema file in the classpath (using the not } ``` -**NOTE**: It's not a requirement to validate both inbound and outbound schemas - You can either use one, or both. +!!! note + It is not a requirement to validate both inbound and outbound schemas - You can either use one, or both. ### Validate function @@ -206,13 +207,14 @@ You can also gracefully handle schema validation errors by catching `ValidationE } ``` -**NOTE**: Schemas are stored in memory for reuse, to avoid loading them from file each time. +!!! note + Schemas are stored in memory for re-use, to avoid loading them from file each time. ## Built-in events and responses For the following events and responses, the Validator will automatically perform validation on the content. -** Events ** +**Events** Type of event | Class | Path to content | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- @@ -230,7 +232,7 @@ For the following events and responses, the Validator will automatically perform SNS | SNSEvent | `Records[*].Sns.Message` SQS | SQSEvent | `Records[*].body` -** Responses ** +**Responses** Type of response | Class | Path to content (envelope) ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index cb856a39a..b4b300fcb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,7 @@ site_name: Powertools for AWS Lambda (Java) site_description: Powertools for AWS Lambda (Java) site_author: Amazon Web Services -site_url: https://docs.powertools.aws.dev/lambda-java/ +site_url: https://docs.powertools.aws.dev/lambda/java/ nav: - Homepage: index.md - Changelog: changelog.md From 45d95189e6fb65f95773ccf3376b2db925bdb8ad Mon Sep 17 00:00:00 2001 From: Philipp Page Date: Fri, 25 Apr 2025 12:36:09 +0200 Subject: [PATCH 6/6] Add versioning.md to llms.txt. --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index b4b300fcb..dd4c40953 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -111,6 +111,7 @@ plugins: - utilities/serialization.md Processes: - processes/maintainers.md + - processes/versioning.md extra_css: - stylesheets/extra.css