Skip to content

Commit 84bc3a5

Browse files
dreamorosisvozza
dreamorosi
and
svozza
authored
chore: add maintainers handbook (#62)
Co-authored-by: Stefano Vozza <[email protected]>
1 parent 517d5d7 commit 84bc3a5

File tree

2 files changed

+293
-1
lines changed

2 files changed

+293
-1
lines changed

‎.github/ISSUE_TEMPLATE/maintenance.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ name: Maintenance
22
description: Suggest an activity to help address tech debt, governance, and anything internal
33
title: "Maintenance: TITLE"
44
labels: ["triage"]
5-
type: "Enhancement"
5+
type: "Task"
66
body:
77
- type: markdown
88
attributes:

‎MAINTAINERS.md‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
# Maintainers Playbook
2+
3+
Playbook for active maintainers of the project and new contributors.
4+
5+
## Overview
6+
7+
> [!Note]
8+
> This is a living document and will be updated as the project evolves.
9+
10+
This document explains who the maintainers are, their responsibilities, and how they should be doing it. If you're interested in contributing, see the [contributing](https://github.com/aws-powertools/powertools-mcp/blob/chore/main/CONTRIBUTING.md) document.
11+
12+
## Current Maintainers
13+
14+
| Maintainer | GitHub ID | Affiliation |
15+
| -------------- | --------------------------------------------------------------------------- | ----------- |
16+
| Andrea Amorosi | [dreamorosi](https://github.com/dreamorosi){target="_blank" rel="nofollow"} | Amazon |
17+
| Henrique Graca | [hjgraca](https://github.com/hjgraca){target="_blank" rel="nofollow"} | Amazon |
18+
| Stefano Vozza | [svozza](https://github.com/svozza){target="_blank" rel="nofollow"} | Amazon |
19+
20+
### Emeritus
21+
22+
Previous active maintainers who contributed to this project.
23+
24+
| Maintainer | GitHub ID | Affiliation |
25+
| ---------------- | ----------------------------------------------------------------------- | ----------- |
26+
| Michael Walmsley | [walmsles](https://github.com/walmsles){target="_blank" rel="nofollow"} | Accenture |
27+
28+
## Issue Types
29+
30+
| Type | Description |
31+
| ----------- | ---------------------------------------------------------------------------------------------------- |
32+
| Bug | Issue representing a bug in the MCP server code, see [Is that a bug?](#is-that-a-bug) for details. |
33+
| Enhancement | Issue representing a new feature or enhancement to the MCP server code. |
34+
| Task | Issue representing a task that needs to be done, such as documentation updates or maintenance tasks. |
35+
36+
## Issue Status Labels
37+
38+
These are the most common labels used by maintainers to categorize the status of issues. They help maintainers and contributors understand the current state of an issue at a glance.
39+
40+
| Type | Description |
41+
| ---------------------- | ----------------------------------------------------------------------- |
42+
| triage | Issue is new and requires maintainers review. |
43+
| researching | Issue is being investigated but not yet confirmed for the backlog. |
44+
| confirmed | Issue is on the backlog and ready for work. |
45+
| in-progress | Issue is being worked on by a maintainer or contributor. |
46+
| pending-release | Issue is completed and waiting to be released. |
47+
| completed | Issue is completed and released. |
48+
| on-hold | Issue is on hold and requires further discussion. |
49+
| need-response | Issue requires a response from the author or customer. |
50+
| need-customer-feedback | Issue requires feedback from one or more customers to reach consensus. |
51+
| need-more-info | Issue requires more information before it's added to the backlog. |
52+
| revisit-in-3-months | Issue is not a priority right now, but should be revisited in 3 months. |
53+
| duplicate | Issue is a duplicate of another issue and will be closed. |
54+
| rejected | Issue is closed due to lack of traction or being a duplicate. |
55+
56+
The following diagram illustrates the issue triage workflow and the most common states an issue can be in:
57+
58+
```mermaid
59+
flowchart TD
60+
%% Define nodes with styles
61+
start[New Issue] --> triage(triage)
62+
63+
%% Triage outcomes
64+
triage --> researching(researching)
65+
triage --> confirmed(confirmed)
66+
triage --> notReadyYet
67+
triage --> notNow
68+
triage --> duplicate(duplicate)
69+
70+
%% Group "Not Ready Yet" states
71+
subgraph notReadyYet[Not Ready Yet]
72+
direction TB
73+
needMoreInfo(need-more-info)
74+
needResponse(need-response)
75+
needCustomerFeedback(need-customer-feedback)
76+
end
77+
78+
%% Group "Not Now" states
79+
subgraph notNow[Not Now]
80+
direction TB
81+
onHold(on-hold)
82+
revisitIn3Months(revisit-in-3-months)
83+
end
84+
85+
%% Researching outcomes
86+
researching --> confirmed
87+
researching --> notReadyYet
88+
researching --> notNow
89+
90+
%% Further workflow
91+
confirmed --> inProgress(in-progress)
92+
inProgress --> pendingRelease(pending-release)
93+
pendingRelease --> completed(completed)
94+
95+
%% Closing paths
96+
duplicate --> closed(closed)
97+
notReadyYet -->|lack of traction| closed
98+
notNow -->|lack of traction| closed
99+
100+
%% Styling
101+
classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px
102+
classDef active fill:#d4f9d4,stroke:#333,stroke-width:1px
103+
classDef waiting fill:#f9f3d4,stroke:#333,stroke-width:1px
104+
classDef hold fill:#f9d4d4,stroke:#333,stroke-width:1px
105+
classDef done fill:#d4d4f9,stroke:#333,stroke-width:1px
106+
classDef closed fill:#ffffff,stroke:#333,stroke-width:1px
107+
108+
class triage,researching waiting
109+
class confirmed,inProgress active
110+
class notReadyYet,notNow,onHold,revisitIn3Months,needMoreInfo,needResponse,needCustomerFeedback hold
111+
class pendingRelease,completed,duplicate done
112+
class closed closed
113+
```
114+
115+
## Other Labels
116+
117+
These are some of the other labels that can be applied to issues and pull requests. They help maintainers and contributors understand the context of an issue or pull request, and how it relates to the project.
118+
119+
| Label | Usage |
120+
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
121+
| not-a-bug | Issue is not a bug, but rather an intended behavior or a feature request. |
122+
| help-wanted | Issue is seeking help from the community. |
123+
| good-first-issue | Issue is a good first issue for new contributors. |
124+
| bug-upstream | Issue is a bug in an upstream dependency and needs to be reported upstream. |
125+
| need-issue | PR is missing a linked issue and might be closed if not addressed. |
126+
| pending-close-response-required | Issue is pending a response from the author or customer and will be closed if no response is received within 1 weeks. |
127+
| breaking-change | Issue or PR that introduces a breaking change and requires careful review. |
128+
| automation | Issue or PR that is related to automation, such as CI/CD workflows or scripts. |
129+
| size/XS | PR between 0-9 LOC |
130+
| size/S | PR between 10-29 LOC |
131+
| size/M | PR between 30-99 LOC |
132+
| size/L | PR between 100-499 LOC |
133+
| size/XL | PRs between 500-999 LOC, often PRs that grown with feedback |
134+
| size/XXL | PRs with 1K+ LOC, largely documentation related or tooling changes that cause large diffs |
135+
136+
## Maintainer Responsibilities
137+
138+
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){target="_blank" rel="nofollow"}. Use those privileges to serve the community and evolve code as follows.
139+
140+
Be aware of recurring ambiguous situations and [document them](#common-scenarios) to help your fellow maintainers.
141+
142+
### Uphold Code of Conduct
143+
144+
Model the behavior set forward by the [Code of Conduct](https://github.com/aws-powertools/powertools-mcp/blob/chore/main/CODE_OF_CONDUCT.md){target="_blank"} 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](https://github.com/aws-powertools/powertools-mcp/blob/chore/main/CODE_OF_CONDUCT.md){target="_blank"}.
145+
146+
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.
147+
148+
### Prioritize Security
149+
150+
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.
151+
152+
Note that this repository is monitored and supported 24/7 by Amazon Security, see [Reporting a Vulnerability](https://github.com/aws-powertools/powertools-mcp/blob/main/SECURITY.md){target="_blank"} for details.
153+
154+
### Review Pull Requests
155+
156+
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.
157+
158+
PRs are [labeled](#other-labels) based on status, content, and use semantic titles. Pay attention to whether labels reflect the current state of the PR and update accordingly.
159+
160+
Use and enforce [semantic versioning](https://semver.org/) pull request titles, as these will be used for versioning and the changelog, as well as [release notes](https://github.com/aws-powertools/powertools-mcp/releases) - make sure they communicate their intent at the human level.
161+
162+
For issues linked to a PR, make sure `pending-release` label is applied to them when merging. [Upon release](#releasing-a-new-version), these issues will be updated with the release version that contains the changes in the PR.
163+
164+
See [Common scenarios](#common-scenarios) section for additional guidance.
165+
166+
### Triage New Issues
167+
168+
Manage [labels](#issue-status-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.
169+
170+
Make sure issues are categorized according to our [issue type definition](#issue-types) and have the right [status](#issue-status-labels).
171+
172+
Use our [labels](#other-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.
173+
174+
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 when you were starting in open source.
175+
176+
See [Common scenarios](#common-scenarios) section for additional guidance.
177+
178+
### Triage Bug Reports
179+
180+
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.
181+
182+
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 would prefer us to do so.
183+
184+
Assess the impact and make the call on whether we need an emergency release. Contact other [maintainers](#current-maintainers) when in doubt.
185+
186+
See [Common scenarios](#common-scenarios) section for additional guidance.
187+
188+
### Triage RFCs
189+
190+
An 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, the trade-offs, and alternative solutions that were part of the research before implementation begins.
191+
192+
Make sure you ask these questions in mind when reviewing:
193+
194+
- Does it use our [RFC template](https://github.com/aws-powertools/powertools-mcp/discussions/new?category=rfcs)?
195+
- Does the proposal address the use case? If so, is the recommended usage explicit?
196+
- Does it focus on the mechanics to solve the use case over fine-grained implementation details?
197+
- Can anyone familiar with the code base implement it?
198+
- If approved, is the author interested in contributing? Do they need any guidance?
199+
- Does this significantly increase the overall project maintenance? Do we have the skills to maintain it?
200+
- If we can't take this use case, are there alternative projects we could recommend? Or does it call for a new project altogether?
201+
202+
When necessary, be upfront that the time to review, approve, and implement an RFC can vary - see [Contribution is stuck](#contribution-is-stuck). Some RFCs may be further updated after implementation, as certain areas become clearer.
203+
204+
Here's an example of RFC with good engagement from the community: [aws-powertools/powertools-lambda-typescript#3500](https://github.com/aws-powertools/powertools-lambda-typescript/discussions/3500).
205+
206+
### Releasing a new version
207+
208+
> [!note]
209+
> This section is a work in progress and will be updated as the project evolves - see [#57](https://github.com/aws-powertools/powertools-mcp/issues/57)
210+
211+
#### Drafting release notes
212+
213+
Visit the [Releases page](https://github.com/aws-powertools/powertools-mcp/releases) and choose the edit pencil button.
214+
215+
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.14.1`.
216+
217+
You'll notice we group all changes based on their [type](#issue-types) like `Enhancement`, `Bug`, `Task`, etc.
218+
219+
**I spotted a typo or incorrect grouping - how do I fix it?**
220+
221+
Edit the respective PR title and update their labels. Then run the [Release Drafter workflow](https://github.com/aws-powertools/powertools-lambda-typescript/**actions**/workflows/release-drafter.yml) to update the Draft release.
222+
223+
!!! note
224+
This won't change the CHANGELOG as the merge commit is immutable. Don't worry about it. We'd rewrite git history only if not doing so can lead to confusion and this should be done by pairing with another maintainer.
225+
226+
**All looking good, what's next?**
227+
228+
The best part comes now. Replace the placeholder `[Human readable summary of changes]` with what you'd like to communicate to customers that this release is all about. Rule of thumb: always put yourself in the customers shoes.
229+
230+
These are some questions to keep in mind when drafting your first or future release notes:
231+
232+
- Can customers understand at a high level what changed in this release?
233+
- Is there a link to the documentation where they can read more about each main change?
234+
- Are there any graphics or [code snippets](https://carbon.now.sh/) that can enhance readability?
235+
- Are we calling out any key contributor(s) to this release?
236+
237+
Once you're happy, hit `Publish release` 🎉🎉🎉.
238+
239+
This will kick off the post-release automations and within a few minutes you should see all issues labeled as `pending-release` notified of the new release and labeled as `completed`.
240+
241+
### Maintain Overall Health of the Repo
242+
243+
Keep the `main` branch at production quality at all times. Backport features as needed. Create release branches and tags to enable future patches.
244+
245+
### Add Continuous Integration Checks
246+
247+
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.
248+
249+
### Negative Impact on the Project
250+
251+
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](https://github.com/aws-powertools/powertools-mcp/blob/main/CODE_OF_CONDUCT.md)
252+
{target="_blank"} violations, deliberate harmful or malicious actions, spam, monopolization, and security risks.
253+
254+
## Common scenarios
255+
256+
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 an appropriate manner as long as [our conduct is consistent](#uphold-code-of-conduct)
257+
258+
### Contribution is stuck
259+
260+
A contribution can get stuck often due to lack of bandwidth and/or language barriers. 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.
261+
262+
In the case of a language barrier or other issues, 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.
263+
264+
In some cases, you may have constrained capacity. Use the `help-wanted` label when you want to signal oto ther maintainers and external contributors that you could use a hand to move it forward.
265+
266+
### Insufficient feedback or information
267+
268+
When in doubt, use the `need-more-info` or `need-customer-feedback` labels to signal more context and feedback are necessary before proceeding. You can also use `revisit-in-3-months` label when you expect it might take a while to gather enough information before you can decide.
269+
270+
Note that issues marked as `need-response` will be automatically closed after 3 weeks of inactivity.
271+
272+
### Crediting contributions
273+
274+
We credit all contributions as part of each [release note](https://github.com/aws-powertools/powertools-mcp/releases){target="_blank"} as an automated process. If you find contributors are missing from the release note you're producing, please add them manually.
275+
276+
### Is that a bug?
277+
278+
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.
279+
280+
Documentation snippets, use of internal components, CI workflows, or unadvertised functionalities are not considered bugs but rather maitenance tasks.
281+
282+
### Mentoring contributions
283+
284+
Always favor mentoring issue authors to contribute, unless they're not interested or the implementation is sensitive (_e.g., complexity, time to release, etc._).
285+
286+
Make use of `help-wanted` and `good-first-issue` to signal additional contributions the community can help.
287+
288+
### Long running issues or PRs
289+
290+
Try offering a 1:1 call in the attempt to get to a mutual understanding and clarify areas that maintainers could help.
291+
292+
In the rare cases where both parties don't have the bandwidth or expertise to continue, it's best to use the `on-hold` or `revisit-in-3-months` labels. After some time has passed, see if it's possible to break the PR or issue into smaller chunks, and eventually close if there is no progress.

0 commit comments

Comments
 (0)