Skip to content

Commit 70da5f0

Browse files
scottgerringscottgerring
authored
docs: Add maintainers guide (#1326)
1 parent 1261e58 commit 70da5f0

File tree

2 files changed

+249
-0
lines changed

2 files changed

+249
-0
lines changed

‎docs/processes/maintainers.md

+247
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
---
2+
title: Maintainers playbook
3+
description: Process
4+
---
5+
6+
<!-- markdownlint-disable MD043 -->
7+
8+
## Overview
9+
10+
!!! note "Please treat this content as a living document."
11+
12+
This is document explains who the maintainers are, their responsibilities, and how they should be doing it. If you're interested in contributing,
13+
see [CONTRIBUTING](https://github.com/aws-powertools/powertools-lambda-java/blob/main/CONTRIBUTING.md){target="_blank"}.
14+
15+
## Current Maintainers
16+
17+
| Maintainer | GitHub ID | Affiliation |
18+
|-----------------------|---------------------------------------------------------------------------------| ----------- |
19+
| Jerome Van Der Linden | [jeromevdl](https://github.com/jeromevdl){target="_blank"} | Amazon |
20+
| Michele Ricciardi | [mriccia](https://github.com/mriccia){target="_blank"} | Amazon |
21+
| Scott Gerring | [scottgerring](https://github.com/scottgerring){target="_blank"} | Amazon |
22+
23+
## Emeritus
24+
25+
Previous active maintainers who contributed to this project.
26+
27+
| Maintainer | GitHub ID | Affiliation |
28+
|----------------|-----------------------------------------------------------------------------------------|---------------|
29+
| Mark Sailes | [msailes](https://github.com/msailes){target="_blank"} | Amazon |
30+
| Pankaj Agrawal | [pankajagrawal16](https://github.com/pankajagrawal16){target="_blank"} | Former Amazon |
31+
| Steve Houel | [stevehouel](https://github.com/stevehouel) | Amazon |
32+
33+
## Labels
34+
35+
These are the most common labels used by maintainers to triage issues, pull requests (PR), and for project management:
36+
37+
| Label | Usage | Notes |
38+
|----------------------------------|---------------------------------------------------------------------------------------------------|----------------------------------------------------|
39+
| triage | New issues that require maintainers review | Issue template |
40+
| bug | Unexpected, reproducible and unintended software behavior | PR/Release automation; Doc snippets are excluded; |
41+
| documentation | Documentation improvements | PR/Release automation; Doc additions, fixes, etc.; |
42+
| duplicate | Dupe of another issue | |
43+
| enhancement | New or enhancements to existing features | Issue template |
44+
| RFC | Technical design documents related to a feature request | Issue template |
45+
| help wanted | Tasks you want help from anyone to move forward | Bandwidth, complex topics, etc. |
46+
| feature-parity | Adding features present in other Powertools for Lambda libraries | |
47+
| good first issue | Somewhere for new contributors to start | |
48+
| governance | Issues related to project governance - contributor guides, automation, etc. | |
49+
| question | Issues that are raised to ask questions | |
50+
| maven | Related to the build system | |
51+
| need-more-information | Missing information before making any calls | |
52+
| status/staged-next-release | Changes are merged and will be available once the next release is made. | |
53+
| status/staged-next-major-release | Contains breaking changes - merged changes will be available once the next major release is made. | |
54+
| blocked | Issues or PRs that are blocked for varying reasons | Timeline is uncertain |
55+
| priority:1 | Critical - needs urgent attention | |
56+
| priority:2 | High - core feature, or affects 60%+ of users | |
57+
| priority:3 | Neutral - not a core feature, or affects < 40% of users | |
58+
| priority:4 | Low - nice to have | |
59+
| priority:5 | Low - idea for later | |
60+
| invalid | This doesn't seem right | |
61+
| size/XS | PRs between 0-9 LOC | PR automation |
62+
| size/S | PRs between 10-29 LOC | PR automation |
63+
| size/M | PRs between 30-99 LOC | PR automation |
64+
| size/L | PRs between 100-499 LOC | PR automation |
65+
| size/XL | PRs between 500-999 LOC, often PRs that grown with feedback | PR automation |
66+
| size/XXL | PRs with 1K+ LOC, largely documentation related | PR automation |
67+
| dependencies | Changes that touch dependencies, e.g. Dependabot, etc. | PR/ automation |
68+
| maintenance | Address outstanding tech debt | |
69+
70+
## Maintainer Responsibilities
71+
72+
Maintainers are active and visible members of the community, and have
73+
[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"}.
74+
Use those privileges to serve the community and evolve code as follows.
75+
76+
Be aware of recurring ambiguous situations and [document them](#common-scenarios) to help your fellow maintainers.
77+
78+
### Uphold Code of Conduct
79+
80+
<!-- markdownlint-disable-next-line MD013 -->
81+
Model the behavior set forward by the
82+
[Code of Conduct](https://github.com/aws-powertools/powertools-lambda-java/blob/main/CODE_OF_CONDUCT.md){target="_blank"}
83+
and raise any violations to other maintainers and admins. There could be unusual circumstances where inappropriate
84+
behavior does not immediately fall within the [Code of Conduct](https://github.com/aws-powertools/powertools-lambda-java/blob/main/CODE_OF_CONDUCT.md){target="_blank"}.
85+
86+
These might be nuanced and should be handled with extra care - when in doubt, do not engage and reach out to other maintainers
87+
and admins.
88+
89+
### Prioritize Security
90+
91+
Security is your number one priority. Maintainer's Github keys must be password protected securely and any reported
92+
security vulnerabilities are addressed before features or bugs.
93+
94+
Note that this repository is monitored and supported 24/7 by Amazon Security, see
95+
[Security disclosures](https://github.com/aws-powertools/powertools-lambda-java/){target="_blank"} for details.
96+
97+
### Review Pull Requests
98+
99+
Review pull requests regularly, comment, suggest, reject, merge and close. Accept only high quality pull-requests.
100+
Provide code reviews and guidance on incoming pull requests.
101+
102+
PRs are [labeled](#labels) based on file changes and semantic title. Pay attention to whether labels reflect the current
103+
state of the PR and correct accordingly.
104+
105+
Use and enforce [semantic versioning](https://semver.org/){target="_blank" rel="nofollow"} pull request titles, as these will be used for
106+
[CHANGELOG](https://github.com/aws-powertools/powertools-lambda-java/blob/main/CHANGELOG.md){target="_blank"}
107+
and [Release notes](https://github.com/aws-powertools/powertools-lambda-java/releases) - make sure they communicate their
108+
intent at the human level.
109+
110+
For issues linked to a PR, make sure `status/staged-next-release` label is applied to them when merging.
111+
[Upon release](#releasing-a-new-version), these issues will be notified which release version contains their change.
112+
113+
See [Common scenarios](#common-scenarios) section for additional guidance.
114+
115+
### Triage New Issues
116+
117+
Manage [labels](#labels), review issues regularly, and create new labels as needed by the project. Remove `triage`
118+
label when you're able to confirm the validity of a request, a bug can be reproduced, etc.
119+
Give priority to the original author for implementation, unless it is a sensitive task that is best handled by maintainers.
120+
121+
Make sure issues are assigned to our [board of activities](https://github.com/orgs/aws-powertools/projects/4).
122+
123+
Use our [labels](#labels) to signal good first issues to new community members, and to set expectation that this might
124+
need additional feedback from the author, other customers, experienced community members and/or maintainers.
125+
126+
Be aware of [casual contributors](https://opensource.com/article/17/10/managing-casual-contributors){target="_blank" rel="nofollow"} and recurring contributors.
127+
Provide the experience and attention you wish you had if you were starting in open source.
128+
129+
See [Common scenarios](#common-scenarios) section for additional guidance.
130+
131+
### Triage Bug Reports
132+
133+
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
134+
labels - always communicate the reason accordingly.
135+
136+
For bugs caused by upstream dependencies, replace `bug` with `bug-upstream` label. Ask the author whether they'd like to
137+
raise the issue upstream or if they prefer us to do so.
138+
139+
Assess the impact and make the call on whether we need an emergency release. Contact other [maintainers](#current-maintainers) when in doubt.
140+
141+
See [Common scenarios](#common-scenarios) section for additional guidance.
142+
143+
### Triage RFCs
144+
145+
RFC is a collaborative process to help us get to the most optimal solution given the context. Their purpose is to ensure
146+
everyone understands what this context is, their trade-offs, and alternative solutions that were part of the research
147+
before implementation begins.
148+
149+
Make sure you ask these questions in mind when reviewing:
150+
151+
- Does it use our [RFC template](https://github.com/aws-powertools/powertools-lambda-java/issues/new?assignees=&labels=RFC%2C+triage&projects=&template=rfc.md&title=RFC%3A+)?
152+
- Does it match our [Tenets](https://docs.powertools.aws.dev/lambda/java/latest/#tenets)?
153+
- Does the proposal address the use case? If so, is the recommended usage explicit?
154+
- Does it focus on the mechanics to solve the use case over fine-grained implementation details?
155+
- Can anyone familiar with the code base implement it?
156+
- If approved, are they interested in contributing? Do they need any guidance?
157+
- Does this significantly increase the overall project maintenance? Do we have the skills to maintain it?
158+
- If we can't take this use case, are there alternative projects we could recommend? Or does it call for a new project altogether?
159+
160+
When necessary, be upfront that the time to review, approve, and implement a RFC can vary -
161+
see [Contribution is stuck](#contribution-is-stuck). Some RFCs may be further updated after implementation, as certain areas become clearer.
162+
163+
Some examples using our initial and new RFC templates: #92, #94, #95, #991, #1226
164+
165+
### Releasing a new version
166+
167+
!!! note "The release process is currently a long, multi-step process. The team is in the process of automating at it."
168+
169+
Firstly, make sure the commit history in the `main` branch **(1)** it's up to date, **(2)** commit messages are semantic,
170+
and **(3)** commit messages have their respective area, for example `feat: <change>`, `chore: ...`).
171+
172+
**Looks good, what's next?**
173+
174+
Kickoff the `Prepare for maven central release` workflow with the intended rekease version. Once this has completed, it will
175+
draft a Pull Request named something like `chore: Prep release 1.19.0`. the PR will **(1)** roll all of the POM versions
176+
forward to the new release version and **(2)** release notes.
177+
178+
Once this is done, check out the branch and clean up the release notes. These will be used both in the
179+
[CHANGELOG.md file](https://github.com/aws-powertools/powertools-lambda-java/blob/main/CHANGELOG.md)
180+
file and the [published github release information](https://github.com/aws-powertools/powertools-lambda-java/releases),
181+
and you can use the existing release notes to see how changes are summarized.
182+
183+
Next, commit and push, wait for the build to complete, and merge to main. Once main has built successfully (i.e. build, tests and end-to-end tests should pass), create a
184+
tagged release from the Github UI, using the same release notes.
185+
186+
Next, run the `Publish package to the Maven Central Repository` action to release the library.
187+
188+
Finally, by hand, create a PR rolling all of the POMs onto the next snapshot version (e.g. `1.20.0-SNAPSHOT`).
189+
190+
191+
### Add Continuous Integration Checks
192+
193+
Add integration checks that validate pull requests and pushes to ease the burden on Pull Request reviewers.
194+
Continuously revisit areas of improvement to reduce operational burden in all parties involved.
195+
196+
### Negative Impact on the Project
197+
<!-- markdownlint-disable-next-line MD013 -->
198+
Actions that negatively impact the project will be handled by the admins, in coordination with other maintainers,
199+
in balance with the urgency of the issue. Examples would be
200+
[Code of Conduct](https://github.com/aws-powertools/powertools-lambda-java/blob/main/CODE_OF_CONDUCT.md){target="_blank"}
201+
violations, deliberate harmful or malicious actions, spam, monopolization, and security risks.
202+
203+
## Common scenarios
204+
205+
These are recurring ambiguous situations that new and existing maintainers may encounter. They serve as guidance.
206+
It is up to each maintainer to follow, adjust, or handle in a different manner as long as
207+
[our conduct is consistent](#uphold-code-of-conduct)
208+
209+
### Contribution is stuck
210+
211+
A contribution can get stuck often due to lack of bandwidth and language barrier. For bandwidth issues,
212+
check whether the author needs help. Make sure you get their permission before pushing code into their existing PR -
213+
do not create a new PR unless strictly necessary.
214+
215+
For language barrier and others, offer a 1:1 chat to get them unblocked. Often times, English might not be their
216+
primary language, and writing in public might put them off, or come across not the way they intended to be.
217+
218+
In other cases, you may have constrained capacity. Use `help wanted` label when you want to signal other maintainers
219+
and external contributors that you could use a hand to move it forward.
220+
221+
### Insufficient feedback or information
222+
223+
When in doubt, use the `need-more-information` label to signal more context and feedback are necessary before proceeding.
224+
225+
### Crediting contributions
226+
227+
We credit all contributions as part of each [release note](https://github.com/aws-powertools/powertools-lambda-java/releases){target="_blank"}
228+
as an automated process. If you find contributors are missing from the release note you're producing, please add them manually.
229+
230+
### Is that a bug?
231+
232+
A bug produces incorrect or unexpected results at runtime that differ from its intended behavior.
233+
Bugs must be reproducible. They directly affect customers experience at runtime despite following its recommended usage.
234+
235+
Documentation snippets, use of internal components, or unadvertised functionalities are not considered bugs.
236+
237+
### Mentoring contributions
238+
239+
Always favor mentoring issue authors to contribute, unless they're not interested or the implementation is sensitive (_e.g., complexity, time to release, etc._).
240+
241+
Make use of `help wanted` and `good first issue` to signal additional contributions the community can help.
242+
243+
### Long running issues or PRs
244+
245+
Try offering a 1:1 call in the attempt to get to a mutual understanding and clarify areas that maintainers could help.
246+
247+
In the rare cases where both parties don't have the bandwidth or expertise to continue, it's best to use the `revisit-in-3-months` 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.

‎mkdocs.yml

+2
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ nav:
1818
- utilities/validation.md
1919
- utilities/custom_resources.md
2020
- utilities/serialization.md
21+
- Processes:
22+
- processes/maintainers.md
2123

2224
theme:
2325
name: material

0 commit comments

Comments
 (0)