diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 173e45e7df..452ca49707 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,7 +1,7 @@ name: Bug report description: Report a reproducible bug to help us improve title: "Bug: TITLE" -labels: ["bug", "triage"] +labels: ["type/bug", "triage"] body: - type: markdown attributes: @@ -76,8 +76,8 @@ body: - type: textarea id: logs attributes: - label: Debugging logs - description: If available, please share [debugging logs](https://awslabs.github.io/aws-lambda-powertools-python/#debug-mode) + label: Execution logs + description: If available, please share some logs making sure to remove any sensitive data render: Shell validations: required: false diff --git a/.github/ISSUE_TEMPLATE/documentation_improvements.yml b/.github/ISSUE_TEMPLATE/documentation_improvements.yml index d52df5b994..93b47d75fc 100644 --- a/.github/ISSUE_TEMPLATE/documentation_improvements.yml +++ b/.github/ISSUE_TEMPLATE/documentation_improvements.yml @@ -1,7 +1,7 @@ name: Documentation improvements description: Suggest a documentation update to improve everyone's experience title: "Docs: TITLE" -labels: ["documentation", "triage"] +labels: ["area/documentation", "triage"] body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 5abeb0a7f4..964a4cc897 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,7 +1,7 @@ name: Feature request description: Suggest an idea for Lambda Powertools title: "Feature request: TITLE" -labels: ["feature-request", "triage"] +labels: ["type/feature-request", "triage"] body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/maintenance.yml b/.github/ISSUE_TEMPLATE/maintenance.yml index b07bfc8fb7..cfd98ca876 100644 --- a/.github/ISSUE_TEMPLATE/maintenance.yml +++ b/.github/ISSUE_TEMPLATE/maintenance.yml @@ -1,7 +1,7 @@ name: Maintenance description: Suggest an activity to help address tech debt, governance, and anything internal title: "Maintenance: TITLE" -labels: ["internal", "triage"] +labels: ["type/internal", "triage"] body: - type: markdown attributes: @@ -32,7 +32,6 @@ body: - Automation - Governance - Tests - - Types - Tracer - Logger - Metrics diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml index b5b1b5c20f..8f6c075476 100644 --- a/.github/ISSUE_TEMPLATE/rfc.yml +++ b/.github/ISSUE_TEMPLATE/rfc.yml @@ -1,7 +1,7 @@ name: Request for Comments (RFC) description: Feature design and detailed proposals title: "RFC: TITLE" -labels: ["RFC", "triage"] +labels: ["type/RFC", "triage"] body: - type: markdown attributes: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e431ff05dc..02304c842c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -32,7 +32,7 @@ ## Checklist -- [ ] [My changes meet the tenets criteria](https://awslabs.github.io/aws-lambda-powertools-python/#tenets) +- [ ] [My changes meet the tenets criteria](https://awslabs.github.io/aws-lambda-powertools-typescript/#tenets) - [ ] I have performed a *self-review* of my own code - [ ] I have *commented* my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas - [ ] I have made corresponding changes to the *documentation* @@ -41,7 +41,7 @@ - [ ] The *code coverage* hasn't decreased - [ ] I have *added tests* that prove my change is effective and works - [ ] New and existing *unit tests pass* locally and in Github Actions -- [ ] Any *dependent changes have been merged and published* in downstream module +- [ ] Any *dependent changes have been merged and published* - [ ] The PR title follows the [conventional commit semantics](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/.github/semantic.yml#L2) ### Breaking change checklist diff --git a/.github/auto_assign-issues.yml b/.github/auto_assign-issues.yml deleted file mode 100644 index 7104232a46..0000000000 --- a/.github/auto_assign-issues.yml +++ /dev/null @@ -1,6 +0,0 @@ -addAssignees: false - -# The list of users to assign to new issues. -# If empty or not provided, the repository owner is assigned -# If addAssignees above is false the below is ignored -assignees: ~ \ No newline at end of file diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 44ad5a6177..a0ae73b1d8 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -2,28 +2,27 @@ change-template: "* $TITLE (#$NUMBER) by @$AUTHOR" categories: - title: 'β‘ Breaking Changes' labels: - - 'breaking-change' + - 'type/breaking-change' - title: 'πNew features and non-breaking changes' labels: - - 'major' - - 'feature' + - 'type/feature' - title: 'π Minor Changes' labels: - - 'enhancement' + - 'type/enhancement' - title: 'π Documentation updates' labels: - - 'documentation' + - 'area/documentation' - title: 'π Bug and hot fixes' labels: - - 'bug' - - 'fix' + - 'type/bug' + - 'type/fix' - title: 'π Deprecations' labels: - - 'deprecated' + - 'type/deprecation' - title: 'π§ Maintenance' labels: - - 'internal' - - 'dependencies' + - 'type/internal' + - 'type/dependencies' exclude-labels: - 'skip-changelog' tag-template: 'v$NEXT_PATCH_VERSION' diff --git a/.github/scripts/constants.js b/.github/scripts/constants.js index e7dd21d8ca..2e3cb78f91 100644 --- a/.github/scripts/constants.js +++ b/.github/scripts/constants.js @@ -25,7 +25,10 @@ module.exports = Object.freeze({ "LABEL_BLOCK_REASON": "need-issue", /** @type {string} */ - "LABEL_PENDING_RELEASE": "pending-release", + "LABEL_PENDING_RELEASE": "status/pending-release", + + /** @type {string} */ + "LABEL_RELEASED": "status/completed", /** @type {string} */ "HANDLE_MAINTAINERS_TEAM": "@awslabs/aws-lambda-powertools-typescript", diff --git a/.github/scripts/label_pr_based_on_title.js b/.github/scripts/label_pr_based_on_title.js index 3f118af489..12465eab1a 100644 --- a/.github/scripts/label_pr_based_on_title.js +++ b/.github/scripts/label_pr_based_on_title.js @@ -1,21 +1,19 @@ -const { PR_NUMBER, PR_TITLE, AREAS } = require("./constants"); +const { PR_NUMBER, PR_TITLE } = require("./constants"); module.exports = async ({github, context, core}) => { - const FEAT_REGEX = /feat(\((.+)\))?(:.+)/ const BUG_REGEX = /(fix|bug)(\((.+)\))?(:.+)/ + const FEAT_REFACTOR_REGEX = /(feat|refactor)(\((.+)\))?(:.+)/ const DOCS_REGEX = /(docs|doc)(\((.+)\))?(:.+)/ const CHORE_REGEX = /(chore)(\((.+)\))?(:.+)/ const DEPRECATED_REGEX = /(deprecated)(\((.+)\))?(:.+)/ - const REFACTOR_REGEX = /(refactor)(\((.+)\))?(:.+)/ - + const labels = { - "feature": FEAT_REGEX, - "bug": BUG_REGEX, - "documentation": DOCS_REGEX, - "internal": CHORE_REGEX, - "enhancement": REFACTOR_REGEX, - "deprecated": DEPRECATED_REGEX, - }; + "type/feature": FEAT_REFACTOR_REGEX, + "type/bug": BUG_REGEX, + "area/documentation": DOCS_REGEX, + "type/internal": CHORE_REGEX, + "type/deprecation": DEPRECATED_REGEX, + } // Maintenance: We should keep track of modified PRs in case their titles change let miss = 0; @@ -33,19 +31,6 @@ module.exports = async ({github, context, core}) => { labels: [label] }); - const area = matches[2]; // second capture group contains the area - if (AREAS.indexOf(area) > -1) { - core.info(`Auto-labeling PR ${PR_NUMBER} with area ${area}`); - await github.rest.issues.addLabels({ - issue_number: PR_NUMBER, - owner: context.repo.owner, - repo: context.repo.repo, - labels: [`area/${area}`], - }); - } else { - core.debug(`'${PR_TITLE}' didn't match any known area.`); - } - return; } else { core.debug(`'${PR_TITLE}' didn't match '${label}' semantic.`); diff --git a/.github/scripts/label_related_issue.js b/.github/scripts/label_related_issue.js index 94ec9c7998..6cfebbdf9b 100644 --- a/.github/scripts/label_related_issue.js +++ b/.github/scripts/label_related_issue.js @@ -6,7 +6,7 @@ const { LABEL_PENDING_RELEASE, HANDLE_MAINTAINERS_TEAM, PR_IS_MERGED, -} = require("./constants") +} = require("./constants"); module.exports = async ({github, context, core}) => { if (IGNORE_AUTHORS.includes(PR_AUTHOR)) { diff --git a/.github/scripts/post_release.js b/.github/scripts/post_release.js new file mode 100644 index 0000000000..5b6781c475 --- /dev/null +++ b/.github/scripts/post_release.js @@ -0,0 +1,113 @@ +const { LABEL_PENDING_RELEASE, LABEL_RELEASED } = require("./constants"); + +/** + * Fetch issues using GitHub REST API + * + * @param {object} gh_client - Pre-authenticated REST client (Octokit) + * @param {string} org - GitHub Organization + * @param {string} repository - GitHub repository + * @param {string} state - GitHub issue state (open, closed) + * @param {string} label - Comma-separated issue labels to fetch + * @return {Object[]} issues - Array of issues matching params + * @see {@link https://octokit.github.io/rest.js/v18#usage|Octokit client} + */ + +const fetchIssues = async ({ + gh_client, + org, + repository, + state = "all", + label = LABEL_PENDING_RELEASE, +}) => { + try { + const { data: issues } = await gh_client.rest.issues.listForRepo({ + owner: org, + repo: repository, + state: state, + labels: label, + }); + + return issues; + } catch (error) { + console.error(error); + throw new Error("Failed to fetch issues"); + } + +}; + +/** + * Notify new release and close staged GitHub issue + * + * @param {object} gh_client - Pre-authenticated REST client (Octokit) + * @param {string} owner - GitHub Organization + * @param {string} repository - GitHub repository + * @param {string} release_version - GitHub Release version + * @see {@link https://octokit.github.io/rest.js/v18#usage|Octokit client} + */ + +const notifyRelease = async ({ + gh_client, + owner, + repository, + release_version, +}) => { + const release_url = `https://github.com/${owner}/${repository}/releases/tag/v${release_version}`; + + const issues = await fetchIssues({ + gh_client: gh_client, + org: owner, + repository: repository, + }); + + issues.forEach(async (issue) => { + console.info(`Updating issue number ${issue.number}`); + + const comment = `This is now released under [${release_version}](${release_url}) version!`; + try { + await gh_client.rest.issues.createComment({ + owner: owner, + repo: repository, + body: comment, + issue_number: issue.number, + }); + } catch (error) { + console.error(error); + throw new Error(`Failed to update issue ${issue.number} about ${release_version} release`) + } + + + // Close issue and remove staged label; keep existing ones + const labels = issue.labels + .filter((label) => label.name != LABEL_PENDING_RELEASE) + .map((label) => label.name); + + try { + await gh_client.rest.issues.update({ + repo: repository, + owner: owner, + issue_number: issue.number, + state: "closed", + labels: [...labels, LABEL_RELEASED], + }); + } catch (error) { + console.error(error); + throw new Error("Failed to close issue") + } + + console.info(`Issue number ${issue.number} closed and updated`); + }); +}; + +// context: https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts + +module.exports = async ({ github, context }) => { + const { RELEASE_VERSION } = process.env; + console.log(`Running post-release script for ${RELEASE_VERSION} version`); + + await notifyRelease({ + gh_client: github, + owner: context.repo.owner, + repository: context.repo.repo, + release_version: RELEASE_VERSION, + }); +}; \ No newline at end of file diff --git a/.github/stale.yml b/.github/stale.yml index 1bb42057ef..d6bdd4c29c 100644 --- a/.github/stale.yml +++ b/.github/stale.yml @@ -2,11 +2,10 @@ only: issues daysUntilStale: 30 daysUntilClose: 7 exemptLabels: - - bug - - documentation - - enhancement - - feature-request - - RFC + - type/bug + - type/bug-upstream + - type/feature-request + - type/RFC staleLabel: pending-close-response-required markComment: > This issue has been automatically marked as stale because it has not had diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef11f898cd..01b305d816 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing Guidelines +# Contributing Guidelines Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community. @@ -6,29 +6,35 @@ documentation, we greatly value feedback and contributions from our community. Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution. -## Table of contents +## Table of contents - [Security issue notifications](#security-issue-notifications) - [Code of Conduct](#code-of-conduct) - [Reporting Bugs/Feature Requests](#reporting-bugsfeature-requests) -- [Contributing via Pull Requests](#contributing-via-pull-requests) - - [Summary](#summary) - - [Step 1: Find something to work on](#step-1-find-something-to-work-on) - - [Step 2: Design](#step-2-design) - - [Step 3: Work your Magic](#step-3-work-your-magic) - - [Step 4: Pull Request](#step-4-pull-request) - - [Step 5: Merge](#step-5-merge) - [Getting Started](#getting-started) - [Setup](#setup) - [Repo Layout](#repo-layout) - [Tests](#tests) - [Unit tests](#unit-tests) + - [Write](#write) + - [Run](#run) - [e2e tests](#e2e-tests) + - [Set up](#set-up) + - [Write](#write-1) + - [Run](#run-1) + - [Automate](#automate) - [Examples](#examples) - [Local documentation](#local-documentation) - [API reference](#api-reference) - [Docs website](#docs-website) - [Conventions](#conventions) +- [Contributing via Pull Requests](#contributing-via-pull-requests) + - [Summary](#summary) + - [Step 1: Find something to work on](#step-1-find-something-to-work-on) + - [Step 2: Design](#step-2-design) + - [Step 3: Work your Magic](#step-3-work-your-magic) + - [Step 4: Pull Request](#step-4-pull-request) + - [Step 5: Merge](#step-5-merge) - [Licensing](#licensing) ## Security issue notifications @@ -252,13 +258,13 @@ Alternatively you can run these two commands: ### Conventions -Category | Convention -------------------------------------------------- | --------------------------------------------------------------------------------- -**Docstring** | We use [JSDoc](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) annotations to provide type information and create API references. -**Style guide** | We use `eslint` to keep our code consistent in terms of style and reducing defects. -**Test coverage** | We use [Jest](https://jestjs.io/) to test our code and [Codecov](https://codecov.io/) to report test coverage. We aim to have 100% test coverage in our unit tests. -**Git commits** | We follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). These are not enforced as we squash and merge PRs, but PR titles are enforced during CI. -**Documentation** | API reference docs are generated from docstrings which should have an Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strives to be concise. +| Category | Convention | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Docstring** | We use [JSDoc](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) annotations to provide type information and create API references. | +| **Style guide** | We use `eslint` to keep our code consistent in terms of style and reducing defects. | +| **Test coverage** | We use [Jest](https://jestjs.io/) to test our code and [Codecov](https://codecov.io/) to report test coverage. We aim to have 100% test coverage in our unit tests. | +| **Git commits** | We follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). These are not enforced as we squash and merge PRs, but PR titles are enforced during CI. | +| **Documentation** | API reference docs are generated from docstrings which should have an Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strives to be concise. | ## Contributing via Pull Requests diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000000..6792654c1a --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,299 @@ +## Table of contents + +- [Overview](#overview) +- [Current Maintainers](#current-maintainers) +- [Emeritus](#emeritus) +- [Labels](#labels) +- [Maintainer Responsibilities](#maintainer-responsibilities) + - [Uphold Code of Conduct](#uphold-code-of-conduct) + - [Prioritize Security](#prioritize-security) + - [Review Pull Requests](#review-pull-requests) + - [Merging Pull Requests](#merging-pull-requests) + - [Triage New Issues](#triage-new-issues) + - [Triage Bug Reports](#triage-bug-reports) + - [Triage RFCs](#triage-rfcs) + - [Releasing a new version](#releasing-a-new-version) + - [Drafting release notes](#drafting-release-notes) + - [Run end to end tests](#run-end-to-end-tests) + - [Releasing a documentation hotfix](#releasing-a-documentation-hotfix) + - [Maintain Overall Health of the Repo](#maintain-overall-health-of-the-repo) + - [Manage Roadmap](#manage-roadmap) + - [Add Continuous Integration Checks](#add-continuous-integration-checks) + - [Negative Impact on the Project](#negative-impact-on-the-project) + - [Becoming a maintainer](#becoming-a-maintainer) +- [Common scenarios](#common-scenarios) + - [Contribution is stuck](#contribution-is-stuck) + - [Insufficient feedback or information](#insufficient-feedback-or-information) + - [Crediting contributions](#crediting-contributions) + - [Is that a bug?](#is-that-a-bug) + - [Mentoring contributions](#mentoring-contributions) + - [Long running issues or PRs](#long-running-issues-or-prs) +- [E2E framework](#e2e-framework) +- [Automation](#automation) + +## Overview + +> **Please treat this content as a living document.** + +This is document explains who the maintainers are (see below), what they do in this repo, and how they should be doing it. If you're interested in contributing, see [CONTRIBUTING](CONTRIBUTING.md). + +## Current Maintainers + +| Maintainer | GitHub ID | Affiliation | +| -------------------------- | ------------------------------------------- | ----------- | +| Andrea Amorosi | [dreamorosi](https://github.com/dreamorosi) | Amazon | +| Sara Gerion | [saragerion](https://github.com/saragerion) | Amazon | +| Florian Chazal | [flochaz](https://github.com/flochaz) | Amazon | +| Chadchapol Vittavutkarnvej | [ijemmy](https://github.com/ijemmy) | Amazon | + +## Emeritus + +Previous active maintainers who contributed to this project. + +| Maintainer | GitHub ID | Affiliation | +| ----------------- | --------------------------------------------- | ----------- | +| Alan Churley | [alan-churley](alan-churley) | CloudCall | +| Nicolas Moutschen | [bahrmichael](https://github.com/bahrmichael) | Stedi | + +## Labels + +These are the most common labels used by maintainers to triage issues, pull requests (PR), and for project management: + +| Label | Usage | Notes | +| -------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- | +| triage | New issues that require maintainers review | Issue template | +| area/documentation | Improvements or additions to documentation | Examples/Readme files; Doc additions, fixes, etc.; | +| area/logger | Items related to the Logger Utility | PR automation | +| area/metrics | Items related to the Metrics Utility | PR automation | +| area/tracer | Items related to the Tracer Utility | PR automation | +| area/idempotency | Items related to the Idempotency Utility | PR automation | +| area/parameters | Items related to the Parameters Utility | PR automation | +| area/automation | Items related to automation like GitHub workflows or CI/CD | PR automation | +| size/XS | PRs between 0-9 LOC | PR automation | +| size/S | PRs between 10-29 LOC | PR automation | +| size/M | PRs between 30-99 LOC | PR automation | +| size/L | PRs between 100-499 LOC | PR automation | +| size/XL | PRs between 500-999 LOC, often PRs that grown with feedback | PR automation | +| size/XXL | PRs with 1K+ LOC, largely documentation related | PR automation | +| customer-reference | Authorization to use company name in our documentation | Public Relations | +| community-content | Suggested content to feature in our documentation | Public Relations | +| do-not-merge | PRs that are blocked for varying reasons | Timeline is uncertain | +| type/bug | Unexpected, reproducible and unintended software behavior | PR/Release automation; Doc snippets are excluded; | +| type/bug-upstream | Bug caused by upstream dependency | | +| type/not-a-bug | New and existing bug reports incorrectly submitted as bug | Analytics | +| type/deprecation | This item contains code deprecation | | +| type/duplicate | This issue is a duplicate of an existing one | Analytics | +| type/feature-request | Issue requesting new or enhancements to existing features | Issue template | +| type/feature | PRs that introduce new features | PR automation | +| type/enhancement | PRs that introduce minor changes, usually to existing features | PR automation | +| type/RFC | Technical design documents related to a feature request | | +| type/internal | PRs that introduce changes in governance, tech debt and chores (linting setup, baseline, etc.) | PR automation | +| type/tests | PRs that add or change tests | PR automation | +| type/dependencies | Changes that touch dependencies, e.g. Dependabot, etc. | Issues/PR automation | +| type/breaking-change | Changes that will cause customer impact and need careful triage | | +| status/blocked | Items which progress is blocked by external dependency or reason | | +| status/confirmed | Items with clear scope and that are ready for implementation | | +| status/discussing | Items that need to be discussed, elaborated, or refined | | +| status/on-hold | Items that are on hold and will be revisited in the future | | +| status/pending-release | Merged changes that will be available soon | Release automation auto-closes/notifies it | +| status/completed | Items that are complete and have been merged and/or shipped | | +| status/rejected | This is something we will not be working on. At least, not in the measurable future | | +| status/pending-close-response-required | This issue will be closed soon unless the discussion moves forward | Stale Automation | +| good-first-issue | Something that is suitable for those who want to start contributing | | +| help-wanted | Tasks you want help from anyone to move forward | Bandwidth, complex topics, etc. | +| need-customer-feedback | Tasks that need more feedback before proceeding | 80/20% rule, uncertain, etc. | +| need-more-information | Missing information before making any calls | | +| need-issue | PR is missing a related issue for tracking change | | + +## Maintainer Responsibilities + +Maintainers are active and visible members of the community, and have [maintain-level permissions on a repository](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization). Use those privileges to serve the community and evolve code as follows. + +Be aware of recurring ambiguous situations and [document them](#common-scenarios) to help your fellow maintainers. + +### Uphold Code of Conduct + +Model the behavior set forward by the [Code of Conduct](CODE_OF_CONDUCT.md) and raise any violations to other maintainers and admins. There could be unusual circumstances where inappropriate behavior does not immediately fall within the [Code of Conduct](CODE_OF_CONDUCT.md). + +These might be nuanced and should be handled with extra care - when in doubt, do not engage and reach out to other maintainers and admins. + +### Prioritize Security + +Security is your number one priority. Maintainer's Github keys must be password protected securely and any reported security vulnerabilities are addressed before features or bugs. + +Note that this repository is monitored and supported 24/7 by Amazon Security, see [Reporting a Vulnerability](SECURITY.md) for details. + +### Review Pull Requests + +Review pull requests regularly, comment, suggest, reject, merge and close. Accept only high quality pull-requests. Provide code reviews and guidance on incoming pull requests. + +PRs are [labeled](#labels) based on file changes and semantic title. Pay attention to whether labels reflect the current state of the PR and correct accordingly. + +Use and enforce [semantic versioning](https://semver.org/) pull request titles, as these will be used for [CHANGELOG](CHANGELOG.md) and [Release notes](https://github.com/awslabs/aws-lambda-powertools-typescript/releases) - make sure they communicate their intent at the human level. + +For issues linked to a PR, our automation should apply the `pending-release` label. Make sure the label is always applied when merging. [Upon release](#releasing-a-new-version), these issues will be notified which release version contains their change. + +See [Common scenarios](#common-scenarios) section for additional guidance. + +### Merging Pull Requests + +Before merging a PR make sure that the title reflects the changes being introduced. + +This project uses the [squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits) strategy which means commits are squashed into a single commit. Instead of seeing all of a contributor's individual commits from a topic branch, the commits are combined into one commit and merged into the default branch. + +This allows you to have control over the commit message although it should match the PR title most of the time. Use and enforce [semantic versioning](https://semver.org/), as these will be used for versioning the next release. + +### Triage New Issues + +Manage [labels](#labels), review issues regularly, and create new labels as needed by the project. Remove `triage` label when you're able to confirm the validity of a request, a bug can be reproduced, etc. Give priority to the original author for implementation, unless it is a sensitive task that is best handled by maintainers. + +Make sure issues are assigned to our [board of activities](https://github.com/orgs/awslabs/projects/76/) and have the right [status](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/roadmap/#roadmap-status-definition). + +Use our [labels](#labels) to signal good first issues to new community members, and to set expectation that this might need additional feedback from the author, other customers, experienced community members and/or maintainers. + +Be aware of [casual contributors](https://opensource.com/article/17/10/managing-casual-contributors) and recurring contributors. Provide the experience and attention you wish you had if you were starting in open source. + +See [Common scenarios](#common-scenarios) section for additional guidance. + +### Triage Bug Reports + +Be familiar with [our definition of bug](#is-that-a-bug). If it's not a bug, you can close it or adjust its title and labels - always communicate the reason accordingly. + +For bugs caused by upstream dependencies, replace `bug` with `bug-upstream` label. Ask the author whether they'd like to raise the issue upstream or if they prefer us to do so. + +Assess the impact and make the call on whether we need an emergency release. Contact other [maintainers](#current-maintainers) when in doubt. + +See [Common scenarios](#common-scenarios) section for additional guidance. + +### Triage RFCs + +RFC is a collaborative process to help us get to the most optimal solution given the context. Their purpose is to ensure everyone understands what this context is, their trade-offs, and alternative solutions that were part of the research before implementation begins. + +Make sure you ask these questions in mind when reviewing: + +- Does it use our [RFC template](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/new?assignees=&labels=RFC%2Ctriage&template=rfc.yml&title=RFC%3A+TITLE)? +- Does the match our [Tenets](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/#tenets)? +- Does the proposal address the use case? If so, is the recommended usage explicit? +- Does it focus on the mechanics to solve the use case over fine-grained implementation details? +- Can anyone familiar with the code base implement it? +- If approved, are they interested in contributing? Do they need any guidance? +- Does this significantly increase the overall project maintenance? Do we have the skills to maintain it? +- If we can't take this use case, are there alternative projects we could recommend? Or does it call for a new project altogether? + +When necessary, be upfront that the time to review, approve, and implement a RFC can vary - see [Contribution is stuck](#contribution-is-stuck). Some RFCs may be further updated after implementation, as certain areas become clearer. + +An example of a successful RFC: [#447](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/447) + +### Releasing a new version + +π§ WIP π§ + +#### Drafting release notes + +Visit the [Releases page](https://github.com/awslabs/aws-lambda-powertools-typescript/releases) and choose the edit pencil button. + +Make sure the `tag` field reflects the new version you're releasing, the target branch field is set to `main`, and `release title` matches your tag e.g., `v1.4.1`. + +You'll notice we group all changes based on their [labels](#labels) like `type/feature`, `type/bug`, `type/documentation`, etc. + +**I spotted a typo or incorrect grouping - how do I fix it?** + +Edit the respective PR title and update their [labels](#labels). Then run the [Release Drafter workflow](https://github.com/awslabs/aws-lambda-powertools-typescript/actions/workflows/release-drafter.yml) to update the Draft release. + +**All looking good, what's next?** + +The best part comes now. Replace the placeholder `[Human readable summary of changes]` with what you'd like to communicate to customers what this release is all about. Rule of thumb: always put yourself in the customers shoes. + +These are some questions to keep in mind when drafting your first or future release notes: + +- Can customers understand at a high level what changed in this release? +- Is there a link to the documentation where they can read more about each main change? +- Are there any graphics or [code snippets](carbon.now.sh/) that can enhance readability? +- Are we calling out any key contributor(s) to this release? + - All contributors are automatically credited, use this as an exceptional case to feature them + +Once you're happy, hit `Publish release` πππ. + +This will kick off the [Publish docs on release](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/.github/workflows/publish-docs-on-release.yml) workflow and within a few minutes you should see the latest version in PyPi, and all issues labeled as `pending-release` will be closed and notified. + +### Run end to end tests + +E2E tests should be ran before every merge to `main` or manually via [run-e2e-tests workflow](https://github.com/awslabs/aws-lambda-powertools-typescript/actions/workflows/run-e2e-tests.yml) before making a release. + +To run locally, you need [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites) and an [account bootstrapped](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) (`cdk bootstrap`). With a default AWS CLI profile configured, or `AWS_PROFILE` environment variable set, run `npm run test:e2e -ws`. + +### Releasing a documentation hotfix + +You can rebuild the latest documentation without a full release via this [GitHub Actions Workflow](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/.github/workflows/publish-docs-on-release.yml). Choose `Run workflow`, keep `main` as the branch, and input the latest Powertools version available i.e. `v1.4.1`. + +This workflow will update both user guide and API documentation. + +### Maintain Overall Health of the Repo + +Keep the `main` branch at production quality at all times. If a PR introduces code changes you should make sure that linting and tests are passing before merging. + +### Manage Roadmap + +See [Roadmap section](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/roadmap/) + +Ensure the repo highlights features that should be elevated to the project roadmap. Be clear about the featureβs status, priority, target version, and whether or not it should be elevated to the roadmap. + +### Add Continuous Integration Checks + +Add integration checks that validate pull requests and pushes to ease the burden on Pull Request reviewers. Continuously revisit areas of improvement to reduce operational burden in all parties involved. + +### Negative Impact on the Project + +Actions that negatively impact the project will be handled by the admins, in coordination with other maintainers, in balance with the urgency of the issue. Examples would be [Code of Conduct](CODE_OF_CONDUCT.md) violations, deliberate harmful or malicious actions, spam, monopolization, and security risks. + +### Becoming a maintainer + +In late 2023, we will revisit this. We need to improve our understanding of how other projects are doing, their mechanisms to promote key contributors, and how they interact daily. + +We suspect this process might look similar to the [OpenSearch project](https://github.com/opensearch-project/.github/blob/main/MAINTAINERS.md#becoming-a-maintainer). + +## Common scenarios + +These are recurring ambiguous situations that new and existing maintainers may encounter. They serve as guidance. It is up to each maintainer to follow, adjust, or handle in a different manner as long as [our conduct is consistent](#uphold-code-of-conduct) + +### Contribution is stuck + +A contribution can get stuck often due to lack of bandwidth and language barrier. For bandwidth issues, check whether the author needs help. Make sure you get their permission before pushing code into their existing PR - do not create a new PR unless strictly necessary. + +For language barrier and others, offer a 1:1 chat to get them unblocked. Often times, English might not be their primary language, and writing in public might put them off, or come across not the way they intended to be. + +In other cases, you may have constrained capacity. Use `help=wanted` label when you want to signal other maintainers and external contributors that you could use a hand to move it forward. + +### Insufficient feedback or information + +When in doubt, use `need-more-information` or `need-customer-feedback` labels to signal more context and feedback are necessary before proceeding. You can also use `status/on-hold` label when you expect it might take a while to gather enough information before you can decide. + +### Crediting contributions + +We credit all contributions as part of each [release note](https://github.com/awslabs/aws-lambda-powertools-typescript/releases) as an automated process. If you find contributors are missing from the release note you're producing, please add them manually. + +### Is that a bug? + +A bug produces incorrect or unexpected results at runtime that differ from its intended behavior. Bugs must be reproducible. They directly affect customers experience at runtime despite following its recommended usage. + +Documentation snippets, examples, use of internal components, or unadvertised functionalities are not considered bugs. + +### Mentoring contributions + +Always favor mentoring issue authors to contribute, unless they're not interested or the implementation is sensitive (_e.g., complexity, time to release, etc._). + +Make use of `help-wanted` and `good-first-issue` to signal additional contributions the community can help. + +### Long running issues or PRs + +Try offering a 1:1 call in the attempt to get to a mutual understanding and clarify areas that maintainers could help. + +In the rare cases where both parties don't have the bandwidth or expertise to continue, it's best to use the `on-hold` label. By then, see if it's possible to break the PR or issue in smaller chunks, and eventually close if there is no progress. + +## E2E framework + +π§ WIP π§ + +## Automation + +π§ WIP π§ \ No newline at end of file diff --git a/README.md b/README.md index c7dd0c0a7d..d97b378def 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# AWS Lambda Powertools for TypeScript +# AWS Lambda Powertools for TypeScript [](https://discord.gg/B8zZKbbyET) @@ -6,17 +6,19 @@ A suite of utilities for AWS Lambda functions to ease the adoption of best pract You can use the library in both TypeScript and JavaScript code bases. -AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available. +> Also available in [Python](https://github.com/awslabs/aws-lambda-powertools-python), [Java](https://github.com/awslabs/aws-lambda-powertools-java), and [.NET](https://awslabs.github.io/aws-lambda-powertools-dotnet/). -**[π Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)** +**[Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[npm](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/roadmap)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)** -## Table of contents +## Table of contents - [Features](#features) - [Getting started](#getting-started) - [Installation](#installation) + - [Lambda layers](#lambda-layers) + - [NPM modules](#npm-modules) - [Examples](#examples) - - [Serverless TypeScript Demo](#serverless-typescript-demo-application) + - [Serverless TypeScript Demo application](#serverless-typescript-demo-application) - [Contribute](#contribute) - [Roadmap](#roadmap) - [Connect](#connect) diff --git a/docs/requirements.txt b/docs/requirements.txt index 33e6747563..8ab5fb126c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,3 @@ mike==1.1.2 -mkdocs-material==8.3.6 -mkdocs-git-revision-date-plugin==0.3.2 -mkdocs-glightbox==0.1.6 \ No newline at end of file +mkdocs-material==8.5.9 +mkdocs-git-revision-date-plugin==0.3.2 \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000000..f449979f2e --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,102 @@ +## Overview + +This is our public roadmap that outlines the high level direction we are working towards, namely [Themes](#themes). We update this document when our priorities change: security and stability is our top priority. + +[See our latest list of activities Β»](https://github.com/orgs/awslabs/projects/76/views/2){target="_blank"} + +## Themes + +!!! info "Operational Excellence is priority number 1." + +Themes are key activities maintainers are focusing on, besides bug reports. These are updated periodically and you can get an idea of the overall progress in the [Milestones section](https://github.com/awslabs/aws-lambda-powertools-typescript/milestones){target="_blank"}. + +### New utilities + +After going GA, we want to start working on new utilities, specifically but not limited to the most commonly asked: **(1)** [Idempotency](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/447) and **(2)** [Parameters](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/846). + +### Lambda Layers + +We want to publish and maintain public Lambda Layers. + +Work on this area is mostly complete and layers are already available in all commercial regions, however we still have some [work to do around automation](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/1124). + +### ES Modules support + +Another one of the most requested features is [ES Modules support](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/521). This topic requires some in-depth investigation to understand how to move forward and how to deal with some of our upstream dependencies. + +When the time comes, we might open a RFC to discuss options. + +### Improve operational excellence + +We continue to work on increasing operational excellence to remove as much undifferentiated heavylifting for maintainers, so that we can focus on delivering features that help you. + +This means improving our automation workflows, and project management, and test coverage. + +## Roadmap status definition + +