docs(maintenance): retire stale process docs by dreamorosi · Pull Request #5618 · aws-powertools/powertools-lambda-typescript

dreamorosi · 2026-09-03T17:02:48Z

Summary

Retires stale process pages that remained published after their removal from the MkDocs navigation in #5426. Consolidates the current contributor and maintainer guidance in the repository root and refreshes related links and examples. This PR is a draft while a few documentation placement decisions remain open.

Changes

Removed the stale 2025 roadmap, the published maintainers page, and docs/contributing/*. Most roadmap items have shipped, and its public-roadmap framing no longer matches the project's stance.
Moved the maintainers' operational playbook into MAINTAINERS.md and checked it against current workflows. This includes releases, npm name reservation, package and CI wiring, Region and layer publishing through bootstrap_region.yml and layer_balance.yml, and a label table rebuilt from the repository's current labels. Retired aspirational governance content and fixed about six broken links.
Moved the non-obvious contributor guidance into CONTRIBUTING.md, including development requirements, end-to-end tests and their cost warning, direct ?template= issue links, and RFC Discussions. Updated the pull request requirements and replaced duplicate convention and testing tables with links to CODING_STANDARDS.md and AGENTS.md.
Corrected the test directory name and documented unpublished workspaces in CODING_STANDARDS.md. Removed the Roadmap link and changed the Parser install example from zod@~3 to zod in README.md.
Changed the RFC reference from an issue to a Discussion and refreshed runtime examples in docs/versioning.md. Fixed malformed iframes and replaced Twitter with X in docs/we_made_this.md.
Verified that markdownlint is clean, mkdocs build passes, and no links to the deleted pages remain.
Left follow-up decisions open for the RFC review checklist location, the serviceName convention placement, and the tenets anchor.

Issue number: n/a — maintenance cleanup

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

Move current contributor and maintainer guidance into the root documents and remove stale published process pages. Refresh related links and examples so the remaining documentation matches current project workflows.

dreamorosi · 2026-09-03T17:06:00Z

-<!-- markdownlint-disable MD013 -->
-[When filing an issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose), please check [existing open](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc), or [recently closed](https://github.com/aws-powertools/powertools-lambda-typescript/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed), issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can.
-<!-- markdownlint-enable MD013 -->
+Still nothing that matches your skill set? Say so on [GitHub Discussions](https://github.com/aws-powertools/powertools-lambda-typescript/discussions) — especially if you'd like mentoring on something you don't feel ready for yet. Contributions are meant to be bi-directional; there's always something we can learn from each other.


Let's remove this

dreamorosi · 2026-09-03T17:06:22Z


-We welcome you to use the GitHub issue tracker to report bugs, suggest features, or documentation improvements.
+- **Documentation.** Look for places that could use a clearer example or a diagram, and keep in mind a diverse audience that often reads English as a second language.
+- **Sample applications.** Using Powertools for AWS Lambda in a new context surfaces rough edges we can't see from the inside.


Let's remove this and adapt the section, we'll retire the sample app in this repo in a future PR

dreamorosi · 2026-09-03T17:08:04Z

+
+| Maintainer                 | GitHub ID                                       | Affiliation |
+| -------------------------- | ----------------------------------------------- | ----------- |
+| Alexander Schueren         | [am29d](https://github.com/am29d)               |             |


Affiliation is now OpenAI

dreamorosi · 2026-09-03T17:08:16Z

+| Maintainer                 | GitHub ID                                       | Affiliation |
+| -------------------------- | ----------------------------------------------- | ----------- |
+| Alexander Schueren         | [am29d](https://github.com/am29d)               |             |
+| Simon Thulbourn            | [sthulb](https://github.com/sthulb)             | Amazon      |


Affiliation is now empty

dreamorosi · 2026-09-03T17:08:27Z

+| Alexander Schueren         | [am29d](https://github.com/am29d)               |             |
+| Simon Thulbourn            | [sthulb](https://github.com/sthulb)             | Amazon      |
+| Sara Gerion                | [saragerion](https://github.com/saragerion)     | Amazon      |
+| Florian Chazal             | [flochaz](https://github.com/flochaz)           | Amazon      |


Affiliation is now empty

dreamorosi · 2026-09-03T17:09:13Z

+| Label                             | Usage                                                                 | Applied by                                               |
+| --------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
+| `triage`                          | Not yet triaged; remove it once you've validated the request or repro | Issue templates                                          |
+| `confirmed`                       | Scope is clear and it's ready for implementation                      | Manual                                                   |


let's remove this, let's make confirmed state implicit by the absence of other blocking labels - also archive the label

dreamorosi · 2026-09-03T17:09:33Z

+| `discussing`                      | Needs to be discussed, elaborated, or refined                         | Manual                                                   |
+| `researching`                     | Under consideration; we'll update once we know more                   | Manual                                                   |


Let's merge these into one, archive the other - very similar anyway

dreamorosi · 2026-09-03T17:10:00Z

+| `rejected`                        | We won't work on this, at least not in the foreseeable future         | `.github/workflows/stale-issues.yml` on close, or manual |
+| `blocked`                         | Progress is blocked by an external dependency or reason               | Manual                                                   |
+| `on-hold`                         | Parked and will be revisited in the future                            | Manual                                                   |
+| `revisit-in-3-months`             | Parked with a rough timer, often paired with `need-customer-feedback` | Manual                                                   |


Retire this and archive the label

dreamorosi · 2026-09-03T17:10:18Z

+| `on-hold`                         | Parked and will be revisited in the future                            | Manual                                                   |
+| `revisit-in-3-months`             | Parked with a rough timer, often paired with `need-customer-feedback` | Manual                                                   |
+| `next-major-version`              | Deferred to the next major version                                    | Manual                                                   |
+| `duplicate`                       | Duplicate of an existing item                                         | Manual                                                   |


Retire this and archive label, same can be done with issue closing reason

dreamorosi · 2026-09-03T17:10:30Z

+| `need-customer-feedback`          | Needs more customer input before deciding or revisiting a decision    | Manual                                                   |
+| `need-response`                   | Waiting on the author; opts the issue into the stale automation       | Manual                                                   |
+| `pending-close-response-required` | Went stale waiting for a response and will be closed unless it moves  | `.github/workflows/stale-issues.yml`                     |
+| `rejected`                        | We won't work on this, at least not in the foreseeable future         | `.github/workflows/stale-issues.yml` on close, or manual |


Retire this and archive, same can be done with issue closing reason

dreamorosi · 2026-09-03T17:10:49Z

+| `next-major-version`              | Deferred to the next major version                                    | Manual                                                   |
+| `duplicate`                       | Duplicate of an existing item                                         | Manual                                                   |
+| `pending-release`                 | Merged and shipping in the next release                               | Manual, when merging the PR                              |
+| `completed`                       | Shipped                                                               | `.github/workflows/post-release.yml`                     |


Remove this and archive label, closed issue already means that

dreamorosi · 2026-09-03T17:11:25Z

+| `RFC`                | Technical design document related to a feature request                             | Manual                                          |
+| `deprecation`        | Contains code deprecation                                                          | Manual                                          |
+| `breaking-change`    | Customer-impacting change that needs careful triage                                | Manual                                          |


Remove and archive all three

dreamorosi · 2026-09-03T17:11:59Z

+| Label                | Usage                                                                              | Applied by                                      |
+| -------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `bug`                | Unexpected, reproducible, unintended runtime behavior                              | `bug_report.yml` issue template                 |
+| `not-a-bug`          | Reported as a bug but isn't one, see [What counts as a bug](#what-counts-as-a-bug) | Manual                                          |


Remove and archive, a bug report that is not a bug becomes a closed as not planned

dreamorosi · 2026-09-03T17:12:40Z

+
+| Label                | Usage                                                                              | Applied by                                      |
+| -------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `bug`                | Unexpected, reproducible, unintended runtime behavior                              | `bug_report.yml` issue template                 |


Remove this, the feature-request, documentation, and internal and archive them, we'll use Issue Types instead

dreamorosi · 2026-09-03T17:13:09Z

+
+Area labels flag which part of the library an item belongs to: `logger`, `metrics`, `tracer`, `parameters`, `idempotency`, `batch`, `parser`, `validation`, `jmespath`, `event-handler`, `commons`, `layers`, and `automation` for CI/CD and workflows.
+
+All of them are applied manually — nothing labels PRs by changed files anymore. There is no area label yet for `data-masking`, `kafka`, or `signer`.


Remove this statement, create the missing labels

dreamorosi · 2026-09-03T17:13:56Z

+| `feature`                                          | Introduces a new feature; groups the PR in the drafted release notes         | Manual                                                 |
+| `enhancement`                                      | Minor change, usually to an existing feature                                 | Manual                                                 |
+| `tests`                                            | Adds or changes tests                                                        | Manual                                                 |


Remove all manual ones and archive the label

dreamorosi · 2026-09-03T17:14:25Z

+
+PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/) — they feed the [changelog](./CHANGELOG.md) and the drafted release notes, so make sure they read well to a human. PR titles, related issues, and the acknowledgment checkbox are enforced by organization-level checks, not by workflows in this repository.
+
+When merging a PR that closes an issue, apply `pending-release` to the issue. `.github/workflows/post-release.yml` swaps it for `completed` on every closed issue once the GitHub release is published.


Both are applied automatically

dreamorosi · 2026-09-03T17:14:38Z

+
+When merging a PR that closes an issue, apply `pending-release` to the issue. `.github/workflows/post-release.yml` swaps it for `completed` on every closed issue once the GitHub release is published.
+
+### Automation you can rely on


Remove this entire section

docs(maintenance): retire stale process docs

e1ca7b8

Move current contributor and maintainer guidance into the root documents and remove stale published process pages. Refresh related links and examples so the remaining documentation matches current project workflows.

powertools-for-aws-oss-automation Bot assigned dreamorosi Sep 3, 2026

powertools-for-aws-oss-automation Bot added the size/XXL PRs with 1K+ LOC, largely documentation related label Sep 3, 2026

dreamorosi commented Sep 3, 2026

View reviewed changes

		\| `discussing` \| Needs to be discussed, elaborated, or refined \| Manual \|
		\| `researching` \| Under consideration; we'll update once we know more \| Manual \|


		Area labels flag which part of the library an item belongs to: `logger`, `metrics`, `tracer`, `parameters`, `idempotency`, `batch`, `parser`, `validation`, `jmespath`, `event-handler`, `commons`, `layers`, and `automation` for CI/CD and workflows.

		All of them are applied manually — nothing labels PRs by changed files anymore. There is no area label yet for `data-masking`, `kafka`, or `signer`.


		PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/) — they feed the [changelog](./CHANGELOG.md) and the drafted release notes, so make sure they read well to a human. PR titles, related issues, and the acknowledgment checkbox are enforced by organization-level checks, not by workflows in this repository.

		When merging a PR that closes an issue, apply `pending-release` to the issue. `.github/workflows/post-release.yml` swaps it for `completed` on every closed issue once the GitHub release is published.


		When merging a PR that closes an issue, apply `pending-release` to the issue. `.github/workflows/post-release.yml` swaps it for `completed` on every closed issue once the GitHub release is published.

		### Automation you can rely on

Uh oh!

Conversation

dreamorosi commented Sep 3, 2026

Summary

Changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dreamorosi Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dreamorosi Sep 3, 2026 •

edited

Loading