Skip to content

Contributing

Everyone, including the repository owner, follows the same path: issue → agreed scope → branch or fork → pull request → checks and review → merge. This is an independent community implementation, not an official AWS distribution. Read the compatibility boundaries before proposing parity work.

1. Open an issue

Search existing issues and the roadmap first, then choose a form in New issue:

  • Bug report: affected module/version or commit, Go/runtime environment, a minimal reproduction, expected behavior, and actual behavior
  • Feature proposal: the problem, proposed behavior, alternatives, compatibility impact, and observable acceptance criteria
  • Documentation, maintenance, or question: the affected page/tool, requested change or question, and what would resolve it

Track one independently verifiable outcome per issue, not one issue per commit. The owner can self-triage and assign their own work. Several commits or partial PRs may share a tracking issue; questions and ideas do not have to become implementation tasks.

Use small synthetic examples. Remove credentials, account identifiers, personal information, and production payloads from logs and attachments. Do not report a suspected vulnerability in a public issue or PR. Use private reporting on the Security page if available; otherwise ask a maintainer for a private reporting route without disclosing the vulnerability publicly.

A maintainer checks for duplicates, confirms the scope and acceptance criteria, and comments that the work is ready. Labels such as bug, enhancement, documentation, help wanted, or good first issue are optional triage aids, not prerequisites. Contributors do not need permission to label or assign issues. Comment before starting to avoid duplicate work. Large API, dependency, or compatibility changes should wait for agreement; a small fix may be proposed as a draft while its issue is being triaged. The owner records the same scope and acceptance decision on their own issue. No response-time guarantee is implied.

2. Work on a branch

External contributors fork the repository; maintainers can branch in the main repository. Do not commit directly to main. For a fork, replace YOUR-USERNAME and 123 below with your account and real issue number:

git clone https://github.com/YOUR-USERNAME/powertools-lambda-go.git
cd powertools-lambda-go
git remote add upstream https://github.com/rambow-cloud/powertools-lambda-go.git
git fetch upstream
git switch -c fix/123-short-description upstream/main

For an existing maintainer checkout:

git fetch origin
git switch -c fix/123-short-description origin/main

Use a focused branch such as fix/123-description, feat/123-description, or docs/123-description. Keep unrelated cleanup in separate issues/PRs. Write documentation and code comments in English; keep feedback respectful and specific. Original contributions use the repository's MIT license; preserve upstream licenses and attribution for third-party material.

3. Implement and verify

Read AGENTS.md and module development. Use Go 1.26 or newer, uv, and Python 3.14 for documentation. Always set CGO_ENABLED=0; do not run the race detector. Root go test ./... does not cover nested modules.

For code changes, add regression tests and run the packaged module and license checks from the repository root:

export CGO_ENABLED=0
uv run --no-project python tools/licenses.py --check
uv run --no-project python tools/modules.py check

In PowerShell, use $env:CGO_ENABLED = '0' instead of export. Use tools/modules.py tidy when dependency metadata must change; keep filesystem replace directives out of go.mod. Focused check --only MODULE runs help iteration, but are not full-workspace acceptance. CI runs the complete module checks and both Linux Lambda architecture builds.

For documentation or contribution-workflow changes:

uv lock --project website --check
uv run --project website --frozen python tools/test_contribution_workflow.py
uv run --project website --frozen python website/check_navigation.py
uv run --project website --frozen python website/check_guides.py
uv run --project website --frozen zensical build --clean --strict --config-file mkdocs.yml

For behavior involving the Lambda runtime, use the maintained local Docker integration runner. It includes the module checks and both architecture builds, so do not repeat them unnecessarily. Cloud AWS testing requires explicit authorization and explicit account/profile configuration; it is not a contribution prerequisite. Keep generated caches, binaries, private evidence, and credentials out of Git. Update project progress only for verified acceptance milestones, not routine wording fixes.

4. Open a pull request

Commit your focused changes and push the feature branch to your fork or the main repository. Open a draft PR targeting main. Use the PR template to explain what changed, why, the actual tests/results, and remaining risks. Prefer titles such as fix(logger): preserve invocation fields or docs: clarify local setup.

In the PR description's Issue section, put one reference per line:

Closes #123

Use Refs #123 for a partial step that should leave its tracking issue open. Fixes and Resolves are also accepted. A same-repository full issue URL or rambow-cloud/powertools-lambda-go#123 is accepted after the keyword. The number must identify a real issue in this repository, not another PR. References inside HTML comments or code blocks do not count. GitHub closes issues from closing keywords when the PR is merged into the default branch; Refs does not auto-close.

The PR contribution policy check verifies the issue reference and nonempty Summary and Testing sections. State the commands and results, or explain why a check is not applicable or blocked; do not claim unrun tests passed. This metadata check cannot judge scope agreement or test quality: maintainers still review both. Owner and dependency-bot PRs need the same tracking issue; a maintainer can edit a bot PR description to add it and the missing sections. Drafts may fail until their description is complete.

The Modules and Lambda artifacts and Build documentation checks run for all PRs, including documentation-only changes. A first-time fork contribution may wait for a maintainer to approve running Actions. This is expected, not a request for credentials or repository write access. PR jobs receive no AWS credentials and do not deploy. Edit the PR body to rerun the policy check; push a new commit to rerun code checks, or ask a maintainer to rerun a transient failure.

5. Review and merge

When ready, leave draft mode and request review. Address feedback on the same branch; keep the PR description and evidence current. Update from main when required and resolve conflicts. A maintainer checks the issue's acceptance criteria, source changes (especially workflows), tests, documentation, and compatibility impact before merging. Passing CI does not guarantee acceptance.

With one maintainer, formal required approvals stay at zero because authors cannot approve their own PRs. The owner still opens an issue and PR, reviews the diff, records test evidence, and waits for all required checks. With a second active maintainer, administrators can require one independent approval.

Prefer squash merging with a meaningful title. A completed issue closes through the PR's closing keyword; leave partial tracking issues open. Delete the merged feature branch when no longer needed. Merging source does not publish Go module versions; releases remain a separate decision.