This repository hosts a record of our project enhancement proposals (PEPs). Any active member of the Good Docs Project can submit a PEP for consideration to the community.
A PEP is a proposal to change some aspect or element of The Good Docs Project, such as major changes to:
- Our community's governance or project management processes
- The project's architecture, such as branching or release strategies
- Legal or financial designations for the project, such as license changes
- High-level technical features or toolchain changes
In general, a PEP is required when a change is substantial and impacts more than one system or other team members. If you're not sure whether a change requires a PEP or not, you are encouraged to submit one.
After a period where the PEP is open for community comment, the project steering committee will vote whether to accept or reject the proposal. General community members may also add their vote, but their votes will be treated as non-binding.
Many mature open source projects use request for comment (RFC) processes to help them make major decisions. The project enhancement proposal (PEP) process is the name we have given to our RFC process.
RFC processes have many benefits, including:
- Empowering community members to share their ideas for improving our project
- Notifying individual contributors of potential impacting changes
- Providing all community members a chance to collaborate on key decisions
- Gathering feedback to improve proposals or reduce the risk from the decisions being made
- Allowing our community to govern itself democratically without making any single individual a bottleneck or gatekeeper
The PEP process has these basic phases:
- Propose - The proposer submits a project enhancement proposal (PEP) and notifies the community.
- Discuss - The community is invited to comment on the PEP for 2-4 weeks.
- Modify - The proposer may choose to revise the original proposal based on community feedback.
- Final comment and vote - After the proposal is modified, the community is invited to offer their final comments for 1-2 weeks. The project steering committee and community members will vote to accept or reject the proposal during this period.
- Implement - If accepted, the community is notified and the proposal is implemented.
In this phase, the proposer submits a project enhancement proposal (PEP) and notifies the community.
To submit a PEP:
-
Fork and clone the
project-enhancement-proposalsrepository to your local machine.If you are not yet comfortable using Git or GitHub, write your proposal in a Google Doc and ask a member of the project steering committee to open the pull request on your behalf.
-
Copy the
pep-template.mdfile from the root directory of this repository. -
Rename the copied file with a short name describing the PEP, such as
release-branching.md. -
Fill in the required sections of the template with details about your proposal.
-
Open a pull request in the
project-enhancement-proposalsrepository that includes your proposed file.Ensure that maintainers are allowed to make modifications to your pull request so that they can assign the PEP a number. Do not submit more than one proposal per pull request.
-
Once the pull request is open, notify the community by posting a brief summary and link to your pull request in:
- The
#proposalsSlack channel - The
#generalSlack channel - The Good Docs groups.io mailing list
- An email or Slack DM to the current Good Docs Project chair
- The
After submitting the pull request, a member of the project steering committee who is in charge of the PEP process will take over community reminders and notifications.
The PEP will be open for community discussion for 2-4 weeks after the community was notified.
During this time, anyone in the community may comment on the proposal by posting comments on the pull request thread.
The length of the open comment period will depend on comment activity. If the community is actively commenting on the PEP after 2 weeks, the commentary period will extend up to a maximum of 4 weeks to allow the discussion to continue.
When making comments, community members should be aware that:
- The project steering committee will use the rough consensus model in which critical, blocking objections are given more consideration than minor, nit-picking objections.
- To that end, community members are encouraged to use the Conventional Comments labels, especially if you consider your comment to be a blocking objection.
- Remember to follow our Code of Conduct and ensure everyone feels safe to participate and express their ideas. Avoid making any personal insults when expressing disagreement.
During or after the general discussion period, the community member that originally submitted the PEP may revise the proposal to incorporate feedback or suggestions from the community.
If the proposer revises the PEP, they should notify the community on the pull request thread (preferred), and/or the #proposals channel or groups.io mailing list thread.
Once the initial comment period has ended, the PEP will enter the final comment status, which will last 1-2 weeks. During the final comment period, the members of the project steering committee and community members may make any final comments and indicate their vote on the proposal:
| Vote | Meaning |
|---|---|
| +1 | In favor of the proposal |
| +0 | Mildly for, but mostly indifferent |
| 0 | Indifferent |
| -0 | Mildly against, but mostly indifferent |
| -1 | Strongly against. This is expected to be accompanied by a reason. |
In order to be accepted, at least half of the current project steering committee members must vote in favor of the proposal. Votes from general community members are non-binding, but will be taken into consideration.
Abstaining or absent votes from project steering committee members will be treated as indifferent votes.
If the PEP is accepted, a member of the project steering committee will merge the proposal and add it to the accepted folder of the project-enhancement-proposals repository.
The proposal is then implemented in the project. If the proposal requires modifying any project documents or repositories, those actions should be taken shortly after the PEP is accepted.
The proposer may choose to withdraw the proposal at any point during the process. It is also possible that the PEP may be accepted, but the implementation may be deferred for a later date.
In creating the PEP process, the authors adapted or were inspired by the following resources, listed alphabetically: