This is an automated email from the ASF dual-hosted git repository. rbowen pushed a commit to branch rbowen-phrasing in repository https://gitbox.apache.org/repos/asf/comdev-site.git
commit 6464cd8655c793073ccfb7cc07db33d93c929615 Author: Rich Bowen <[email protected]> AuthorDate: Fri Jul 25 16:26:31 2025 -0400 Phrasing/Voice improvements to PMC docs. --- source/pmc/chair.md | 66 ++++++++++--------------- source/pmc/community-growth.md | 110 ++++++++++++++++++++--------------------- source/pmc/new-member.md | 81 +++++++++++++++--------------- source/pmc/reporting.md | 95 +++++++++++++++++------------------ source/pmc/responsibilities.md | 110 +++++++++++++++++++---------------------- 5 files changed, 219 insertions(+), 243 deletions(-) diff --git a/source/pmc/chair.md b/source/pmc/chair.md index dd6aca53..49dec8ec 100644 --- a/source/pmc/chair.md +++ b/source/pmc/chair.md @@ -3,23 +3,22 @@ title: PMC Chair tags: ["pmc","chair"] --- -The PMC Chair acts as the voice of the project to the board, and is -responsible for filing a quarterly report. They are not the project -leader, but are a peer of the other PMC members, who has been selected, -for a time, to take the role of secretary and spokesperson. +The PMC Chair serves as the project's voice to the board and handles +quarterly reporting. -The PMC Chair is **not** the de-facto project leader. While they are -usually a senior, well-respected member of the community, they are a -peer, with a few additional duties. +While typically a senior, respected community leader, the Chair is +**not** the project leader but a peer among PMC members, with the same +voting rights and authority as other PMC members, who has accepted +additional secretarial and spokesperson responsibilities. -The Chair should be familiar with the [assigned +The Chair should familiarize themselves with the [assigned duties](https://www.apache.org/dev/pmc.html#chair) of the role. {{% toc %}} ## Secretarial duties -The Chair is responsible for completing the necessary "paperwork" when +The Chair is responsible for completing the necessary processes when new committers and PMC members are added. See the [process for adding new @@ -30,48 +29,37 @@ these requirements. ## Reporting -The Chair is also responsible for [filing the quarterly project report](/pmc/reporting) to -the board of directors. +The Chair [files the quarterly project report](/pmc/reporting) to the +board of directors. ## Moderating discussion -As the name implies, the Chair may occasionally need to step in to -moderate discussion, to ensure that a community is conducting itself -with decorum, and not straying into divisive discussion. +The Chair may need to moderate discussions to ensure the community +maintains appropriate conduct and avoids divisive conversations. -The Chair has been selected because they are a respected member of the -community, and so should not be hesitant to step in and state what the -community standards are, and enforce the expectation that community members -behave in appropriate ways on official communication channels. +Since the Chair has been selected as a respected community member, they +should confidently establish community standards and enforce +expectations for appropriate behavior on official communication +channels. ## Selecting a new Chair -A project may periodically select a new Chair. +Projects may periodically select a new Chair. -Some projects do this every year or two, while others keep the same Chair -for many years. A Chair might step down because they no longer have time -for the role, or simply to give someone else an opportunity. +Some projects rotate Chairs every year or two, while others maintain +the same Chair for many years. A Chair might step down due to time +constraints or to provide others with leadership opportunities. -Candidates for Chair should be made aware of the work load associated -with the position, to ensure that they have the availability for the -role, and clearly understand what they're getting into. +Inform Chair candidates about the workload to ensure they have +sufficient availability and understand the role's requirements. -The outgoing Chair is encouraged to spend some time mentoring the -incoming Chair, and familiarizing them with the duties, to ensure their -success in the role. +The outgoing Chair should mentor the incoming Chair, familiarizing them +with duties to ensure a successful transition. ## See also: -Newly Chairs are sent [this -advice](https://svn.apache.org/repos/private/foundation/officers/advice-for-new-pmc-chairs.txt), -and you're encouraged to read that thoroughly. They should also be -familiar with [published +New Chairs receive [this +advice](https://svn.apache.org/repos/private/foundation/officers/advice-for-new-pmc-chairs.txt) +and should read it thoroughly. They should also review [published policies](https://www.apache.org/dev/pmc.html#policy) for PMCs. - - -(There's some advice for new chairs here: -https://svn.apache.org/repos/private/foundation/officers/advice-for-new-pmc-chairs.txt -- but it's plain text, fairly terse, and behind a password.) - - diff --git a/source/pmc/community-growth.md b/source/pmc/community-growth.md index 1609febe..88dc0b21 100644 --- a/source/pmc/community-growth.md +++ b/source/pmc/community-growth.md @@ -3,90 +3,90 @@ title: Community Growth tags: ["pmc","committers","community"] --- -Growing your project community takes work. This document makes practical -suggestions of how to encourage people to get involved in your project. +Building a thriving project community requires intentional effort. +This guide provides practical strategies to attract and engage +contributors in your project. {{% toc %}} ## Publish a roadmap -Volunteers can work on whatever they want, and so we have a tendency to -not want to tell them what to work on. However, publishing a roadmap, or -even a wishlist of features or improvements that are desired, can give -people an idea of where they might be able to get involved. +While volunteers choose their own contributions, providing direction +helps them find meaningful ways to get involved. Publishing a roadmap +or wishlist of desired features and improvements gives potential +contributors clear entry points. -This also gives a clear sense that the project has ambitions, and is -going somewhere, rather than that it is stagnating. +A roadmap demonstrates that your project has clear goals and +momentum, signaling growth rather than stagnation. -It can be very challenging to keep a roadmap current. Having a mechanism -for tagging open issues with `proposal` or `roadmap` and -automatically extracting that into a web page can help with this. +Keeping a roadmap current can be challenging. Consider implementing +a mechanism for tagging open issues with `proposal` or `roadmap` +labels and automatically extracting them into a web page to +streamline this process. ## Periodically publish the open issue list -Your ticket tracker allows you to periodically summarize the open -issues. Sending this to the dev@ list reminds people that there are -things to work on, and gives them permission, and encouragement, to do -so. +Regularly share summaries of open issues from your ticket tracker +with the dev@ list. This reminds contributors that work is available +and encourages them to get involved. Consider creating [good first -issues](/committers/good-first-issues.html) as a place for new -contributors to get started. +issues](/committers/good-first-issues.html) as entry points for new +contributors. ## Clearly document contribution processes -Double-check that your "how to contribute / build / test / submit PR" -documentation is super clear and easy to follow. Long-time committers -on a project often forget all the institutional knowledge they just -"know", so ensuring the "getting started" document actually works -for newcomers is always worth looking at. +Ensure your contribution documentation -- covering how to contribute, +build, test, and submit pull requests -- is clear and easy to follow. +Experienced committers often overlook the institutional knowledge +they take for granted, so regularly review your "getting started" +documentation from a newcomer's perspective. -Encourage newcomers to talk about, and document, their pain points -during their first contributions, and work towards fixing, or at least -documenting, those things. +Encourage new contributors to share and document their pain points +during their first contributions. Work toward addressing or at least +documenting these challenges to improve the experience for future +contributors. + +Do not neglect non-code contributions as you think about where people +can get involved. ## Publish your contributor ladder -A [contributor ladder](/contributor-ladder.html) is a description of -various levels of access and responsibility a contributor can progress -through in your project. This is typically the path from contributor, to -committer, to PMC member. +A [contributor ladder](/contributor-ladder.html) describes the various +levels of access and responsibility contributors can progress through +in your project -- typically from contributor to committer to PMC member. -Explicitly publish your requirements for each step. For example, if you -require ten non-trivial patches accepted, or perhaps 3 months of -involvement, document this on your website so that people don't feel -that it's random, or that they are driving in the dark. +Clearly document requirements for each level. For example, if you require +ten substantial patches or three months of involvement, publish these +criteria on your website. This prevents contributors from feeling the +process is arbitrary or unclear. -Consider lowering your bar to entry. Remember that while the risk of -inviting someone "too early" is that they'll break something, that's why -you have version control - so you can revert those changes. However, the -risk of inviting someone too late is that they'll give up and go away -forever. +Consider lowering your entry barriers. Remember that inviting someone +"too early" risks temporary issues that version control can fix, but +inviting someone too late risks losing them permanently. ## Engage with big users -If you are aware of companies that rely on your project, encourage them -to think about what they would do if the project retired. This often -leads to those companies realizing the value they get "for free", and -starting to contribute in some way. +Reach out to companies that depend on your project and ask them to consider +what would happen if the project were discontinued. This often leads +organizations to recognize the value they receive and motivates them +to start contributing in meaningful ways. ## Be transparent about project risk -If your project is actually at risk of retiring due to lack of community -engagement, be transparent about this. Tell your dev and user lists -about the risk, and tell them specifically where you need help. +If your project faces retirement due to insufficient community engagement, +communicate this openly. Tell your dev and user lists about the specific +risks and where you need help. Think about non-code needs that your +project has, and be specific about how these could be addressed. -While many users are content to simply consume, when they become aware -that the project is at risk, it often inspires people to think about -ways they can get involved. +While many users are content to consume your project passively, awareness +of project risks often motivates them to contribute. ## Come talk to us -You're always welcome to come talk to the Community Development project, -for advice and resources. We don't always have all of the answers, but -we can help you think about the problem, and suggest possible solutions. - -Engage with one of our [working groups](/workinggroups/) to help -implement some of the above advise. - +The Community Development project welcomes discussions about community growth +challenges. While we don't have all the answers, we can help you analyze +problems and explore potential solutions. +Join one of our [working groups](/workinggroups/) to help implement these +strategies. diff --git a/source/pmc/new-member.md b/source/pmc/new-member.md index 3f9a1ac6..c07b1e71 100644 --- a/source/pmc/new-member.md +++ b/source/pmc/new-member.md @@ -3,62 +3,61 @@ title: New PMC Members tags: ["pmc","election"] --- -You've been invited to join a project PMC? Congratulations! What should -you do now? +Congratulations on your invitation to join a project PMC! Here's what +you should do next. -Being part of an ASF Project Management Committee is more than just an -acknowledgement of your contributions. It's a new level of -responsibility for the project's health and sustainability. The Board of -Directors is relying on you to provide oversight of the project code, -and project community +Joining an ASF Project Management Committee represents more than +recognition of your contributions -- it's a new level of responsibility +for the project's health and sustainability. The Board of Directors +relies on you to provide oversight of the project code and community. ## Join the conversation -If you haven't already, you need to subscribe to the PMC/Private mailing -list. This is the list on which confidential PMC business is conducted, -and is also the channel that the Board uses to contact the PMC. +Subscribe to the PMC/Private mailing list if you haven't already. This +list handles confidential PMC business and serves as the Board's +communication channel with the PMC. -To subscribe to the private list, send blank email to the address -private-subscribe@**PROJECT**.apache.org (replacing **PROJECT** with -your specific project name). Alternately, you can visit the private list -on [lists.apache.org](https://lists.apache.org) (you'll need to log in) -and click the blue "Subscribe to list" button in the left column. +To subscribe to the private list, send a blank email to +private-subscribe@**PROJECT**.apache.org (replace **PROJECT** with +your project name). Alternatively, visit the private list on +[lists.apache.org](https://lists.apache.org) (login required) and +click the blue "Subscribe to list" button in the left column. See also [these tips for using the private mailing list](https://community.apache.org/pmc/responsibilities.html#conducting-business) -We also encourage you to join the developer and user mailing lists, if -you're not already on them. This is where the day-to-day business of the -project happens. It's also one place where you will interact with your -users, and understand their pains and needs. +Join the developer and user mailing lists if you're not already +subscribed. These lists handle the project's day-to-day business and +provide opportunities to interact with users, understanding their needs +and challenges. -Take a moment to introduce yourself on the dev list, if you're not -already well known there. You might include such information as where -you are in the world, what portion of the project you're most engaged -with, and what communications channel you're most accessible on. +Introduce yourself on the dev list if you're not well known there. +Include information such as your location (and time zone), which parts +of the project you work on most, and your preferred communication channels. -This will help developers know when you're likely to be available, how -to get in touch with you, and what topics you're most likely to be able -to help them with. +This helps developers know when you're available, how to contact you, +and which topics you can best assist with. -## Read the docs -There are policies and procedures for how the PMC should conduct itself. -You are expected to [read, understand, and abide by these -policies](https://www.apache.org/dev/pmc.html#policy) +## Read the documentation -Also have a look at the [overview of PMC -responsibilities](https://community.apache.org/pmc/responsibilities.html) to -understand best practices of governing your project. Two other key -documents are about [maintaining project independence](https://apache.org/foundation/policies/conduct), -and [protecting your project's trademarks](https://apache.org/foundation/marks/responsibility). +Familiarize yourself with policies and procedures for PMC conduct. You +must [read, understand, and follow these +policies](https://www.apache.org/dev/pmc.html#policy). -## Ask a lot of questions +Review the [overview of PMC +responsibilities](https://community.apache.org/pmc/responsibilities.html) +to understand best practices for governing your project. Two other key +documents cover [maintaining project +independence](https://apache.org/foundation/policies/conduct) and +[protecting your project's +trademarks](https://apache.org/foundation/marks/responsibility). -As you get used to your new role on the PMC, be sure to ask lots of -questions. Don't be afraid to question the status quo. As why things are -done the way they are, particularly if you see a chance to improve. -Your [beginner's mind](https://en.wikipedia.org/wiki/Shoshin) can offer -insights that more senior members are blind to. +## Ask questions +As you adjust to your new PMC role, ask plenty of questions. Don't +hesitate to question existing practices. Ask why things are done +certain ways, especially when you see improvement opportunities. Your +[beginner's mind](https://en.wikipedia.org/wiki/Shoshin) can provide +insights that experienced members might overlook. diff --git a/source/pmc/reporting.md b/source/pmc/reporting.md index bb48ec6b..5d86eca1 100644 --- a/source/pmc/reporting.md +++ b/source/pmc/reporting.md @@ -3,10 +3,11 @@ title: PMC Reporting tags: ["pmc","reporting"] --- -A PMC is required to file a report to the Board of Directors every -quarter, on a schedule determined by the Board. +Each PMC must submit a quarterly report to the Board of Directors +according to a schedule set by the Board. -You can find your project's reporting schedule on +You can find your project's reporting schedule by visiting the +committe's page on [projects.apache.org](https://projects.apache.org/committees.html). You will also receive a reminder from the Secretary a few weeks prior to your report's due date. @@ -17,65 +18,61 @@ The *official* record of PMC reporting schedules is the file ## Writing a report -The report to the board is expected to contain certain sections. See the -[detailed instructions for writing a board -report](https://www.apache.org/foundation/board/reporting). +While you may use the [reporter tool](https://reporter.apache.org) +to draft your report, avoid submitting auto-generated content. Instead, +use this opportunity to reflect thoughtfully on your project's health, +objectives, and any challenges you're facing. Take time to be introspective +about your project's short- and long-term goals and identify any risks or concerns. -You may (but are not required to) use the [reporter -tool](https://reporter.apache.org) to draft your report. However, do -**not** simply submit an auto-generated report. You are expected to take -this time to be introspective about your project's health, short- and -long-term objectives, and any risks or concerns facing your project. +Consider including thse important topics in your report: -Important things you should mention might include (but are not limited to): - -* Changes to technology trends that will influence the direction of your - project -* A very active individual, or company, entering or exiting from the project -* A merger or acquisition between active participant organizations in +* Technology trend changes that will influence your project's direction +* A very active contributor, or company, joining or leaving the project +* Mergers or acquisitions between active participant organizations in your project -* A boost or decline in your project's momentum, or popularity, that may - result in community changes +* Notable increases or decreases in your project's momentum or popularity + that may affect the community -Remember that reports are made public once the board minutes are -approved, and craft your phrasing accordingly. Sections that are -intended to be Foundation-confidential should be enclosed in *private* +While the Board of Directors is your primary audience, +reports become [publicly available](https://whimsy.apache.org/board/minutes/) +once the board minutes are approved. Mark any +Foundation-confidential sections with <private>...</private> tags, as described in the formal documentation above. -While the Chair can write the report on their own, you are encouraged to -consult with the entire PMC for input on the report, perhaps even -drafting it with everyone able to contribute. +The Chair is responsible for ensuring that the report is filed, but it +should represent the voice of the entire PMC. Consult with the entire PMC as +you draft the report. Many projects discuss drafts on on the dev list, +giving the broader community the opportunity to provite input as well. -The report can be submitted via the [reporter -tool](https://reporter.apache.org), the [agenda -tool](https://whimsy.apache.org/board/agenda), or committed directly to -the [subversion +Submit your report via the [reporter tool](https://reporter.apache.org), +the [agenda tool](https://whimsy.apache.org/board/agenda), or commit it +directly to the [subversion repository](https://svn.apache.org/repos/private/foundation/board). ## What makes a good board report -As with anything you write, the most important thing to keep in mind -when writing your board report is who your audience is. +When writing your board report, keep your audience in mind. + +The primary audience of your report is the board of directors. While +board membes may not be experts in your specific technology, they focus +on project health and sustainability. -The primary audience of your report is, of course, the board of -directors. They are not, generally, experts on your particular technology. They are, -rather, interested in the health and sustainability of the project. -Questions to consider include: +Consider these key questions: * Do you have enough active participants - both committers and PMC members - - to respond to urgent bugs or security? -* Have you responded to any questions or comments that the board made on + to respond to urgent bugs or security? Think about non-technical, as + well as technical roles. +* Have you addressed any questions or comments that the board made on your previous report? -* Have you pointed out major achievements, or challenges, encountered in - the past quarter that an outsider would have missed? +* Have you highlighted major achievements or challenges in the past + quarter than an outsider might have missed? -The secondary audience of your report is the general public. The minutes -of board meetings are -[published](https://apache.org/foundation/board/calendar.html) for our users, -sponsors, the press, and the general public to read. Consider that -audience when writing. For example, if there's a story that you'd like -the press to tell about your project, you might mention it, and provide -a quote that you'd like to see in an article. +Your secondary audience is the general public. The board meeting minutes are +[published](https://apache.org/foundation/board/calendar.html) for users, +sponsors, the press, and the general public to read. Consider this +audience when writing. For example, if you want the press to tell a particular +story about your project, mention it and provide +a quote suitable for an article. If there's something you wish to bring to the attention of the board, but isn't for public consumption, enclose it in <private> tags so @@ -89,15 +86,15 @@ Private tags should be alone on a line </private> ``` -The report isn't just a once-a-quarter box to check -- it's your +The report isn't just a once-a-quarter box to check -- it's your opportunity to tell the story of your project, celebrate your accomplishments, ask for help or advice on challenges you're facing, and identify places where new contributors might find something to work on. -We encourage you to look at [past board +We encourage you to review [past board reports](https://apache.org/foundation/board/calendar.html) for inspiration from -other projects' reports. +other projects. <!-- TODO * Add links to recommended/good reports to emulate. diff --git a/source/pmc/responsibilities.md b/source/pmc/responsibilities.md index e648f05a..07f2fb51 100644 --- a/source/pmc/responsibilities.md +++ b/source/pmc/responsibilities.md @@ -3,39 +3,36 @@ title: PMC Responsibilities tags: ["pmc","governance"] --- -The Project Management Committee (PMC) is responsible for the oversight -of the project, including technical decisions, ensuring that the project -is operating in accordance with ASF norms, adding new members to the -project, and voting on releases. +The Project Management Committee (PMC) oversees the project, including +technical decisions, ensuring compliance with ASF standards, adding +new members, and approving releases. {{% toc %}} ## Conducting Business -The PMC is expected to conduct all of its business on the public -developers mailing list, in the full view of the community. +The PMC must conduct all business on the public developers mailing list, +maintaining full community visibility. -Every PMC also has a private@ list, which is for communication about -private matters, such as discussion of proposed committers, proposed -new PMC members, or confidential security issues. Do not use it for discussion -of features, roadmap, or other technical decisions. +Every PMC has a private@ list reserved for confidential matters such as +discussing proposed committers, potential PMC members, or security issues. +Do not use the private list for features, roadmap discussions, or other +technical decisions, as this cuts the community out of the process. -The Board of Directors will occasionally send you comments or queries, -often related to your quarterly board report. Any PMC member can, and -should, respond to these. You should not wait for the Chair to respond -to these queries. +The Board of Directors occasionally sends comments or queries, often +regarding your quarterly board report. Any PMC member can and should +respond to these inquiries -- don't wait for the Chair to handle them. -The PMC is tasked with making decisions on the direction of the project, -They can, and should, also incorporate the voice of the larger community -in these decisions. However, if a vote is taken, only the votes of the -PMC are binding on the outcome. Other community members may vote as -well, but those votes are advisory only, and not binding. +The PMC makes decisions about project direction and should incorporate +input from the broader community. However, when votes are taken, only +PMC votes are binding. Community members are encouraged to vote, but +their votes serve as advisory input only. -A PMC member may veto a technical decision, such as a proposed patch. -However, they must be able to back this veto up with a technical reason, -and be willing to discuss possible resolutions to their objection. +PMC members may veto technical decisions, such as proposed patches, but +must provide technical justification and engage in discussion to resolve +their objections. -Further discussion of voting may be found on the [Foundation +For more information about voting procedures, see the [Foundation website](https://www.apache.org/foundation/voting.html). ## Protecting your brand @@ -47,47 +44,42 @@ site](https://apache.org/foundation/marks/responsibility). ## Making a release -The process for releasing a official Apache software artifact may be -found on the [Infra -website](https://infra.apache.org/release-publishing.html). As a PMC -member, you are expected to read and understand that process. +The process for releasing official Apache software artifacts is documented +on the [Infra website](https://infra.apache.org/release-publishing.html). +As a PMC member, you must read and understand this process. -When you vote on a release, it should be an indication that you have -actually tested that release. In your vote email, rather than merely -voting +1 or -1, also indicate what you tested, and on what -platform(s). +When voting on a release, actually test the release candidate. In your vote +email, specify what you tested and on which platforms, rather than simply +voting +1 or -1. ## Ensuring Project Health -The PMC is tasked individually and collectively with ensuring that the -project is behaving according to ASF policies and norms. In this -responsibility, PMC members act as individuals, not as representatives -of their employer, or other third-party interests. The reputation of the -project, and the ASF in general, is delegated to PMC members in this -respect. - -Projects should [operate in a vendor neutral fashion](https://community.apache.org/projectIndependence.html). That is to say, any -project participant has an equal voice, unrelated to the employer or -lack thereof. Evidence that a project is favoring one company or -organization over another is a serious offense. For example, if members -of a particular organization are favored over another, for either -addition to the committer roll, the PMC, or for acceptance of their -patches, this is an indication that the employer is exerting undue -influence over the direction of the project. - -The PMC is also expected to set the tone for conduct and interactions in -the project. They can, and should, call out behavior that is in conflict -with ASF norms, such as bullying, racist or sexist discussions, or other -abusive behavior. PMCs may adopt a specific Code of Conduct, or simply -follow the [ASF's general Code of Conduct](https://apache.org/foundation/policies/conduct). +The PMC is individually and collectively responsible for ensuring the +project operates according to ASF policies and standards. In this role, +PMC members act as individuals, not as representatives of their employers +or other third-party interests. The reputation of both the project and the +ASF depends on PMC members fulfilling this responsibility. + +Projects must [operate in a vendor-neutral +fashion](https://community.apache.org/projectIndependence.html). Every project +participant should have an equal voice, regardless of their employer or +employment status. Evidence that a project favors one company or organization +over another constitutes a serious violation. For example, if members of a +particular organization receive preferential treatment for committer status, +PMC membership, or patch acceptance, this indicates undue employer influence +over the project. + +The PMC sets the tone for conduct and interactions within the project. +Members can and should address behavior that conflicts with ASF standards, +including bullying, discriminatory discussions, or other abusive behavior. +PMCs may adopt a specific Code of Conduct or follow the [ASF's general +Code of Conduct](https://apache.org/foundation/policies/conduct). ## Adding Community Members -The PMC is also tasked with the sustainability of the project. An -important part of this is regularly [adding new +The PMC ensures project sustainability by regularly [adding new committers](/pmc/adding-committers.html) and [new PMC -members](/pmc/adding-pmc-members.html). This is not the sole role of the -chair. Rather, every PMC member can, and should, regularly look at who -is participating in the project, and evaluate whether they should be -invited to the next [rung of the contributor -ladder](/contributor-ladder.html). +members](/pmc/adding-pmc-members.html). This responsibility extends beyond +the chair -- every PMC member should regularly evaluate project participants +and consider whether they should be invited to the next [level of the +contributor ladder](/contributor-ladder.html).
