From 03c0b8462db1cc7c78b237f4298ef41301a2e74f Mon Sep 17 00:00:00 2001 From: Tiago Castro Date: Tue, 17 Dec 2024 23:15:04 +0000 Subject: [PATCH] docs: fix broken links and a few typos Signed-off-by: Tiago Castro --- .../pr-workflow.md | 56 +++++------ .../security/security-guidelines.md | 16 ++-- .../content/maintainers/templates/_index.md | 6 +- .../templates/governance-elections.md | 18 ++-- .../templates/governance-maintainer.md | 72 +++++++-------- .../templates/governance-subprojects.md | 92 +++++++++---------- 6 files changed, 130 insertions(+), 130 deletions(-) diff --git a/website/content/maintainers/community/contributor-growth-framework/pr-workflow.md b/website/content/maintainers/community/contributor-growth-framework/pr-workflow.md index 79d92973..92e49d97 100644 --- a/website/content/maintainers/community/contributor-growth-framework/pr-workflow.md +++ b/website/content/maintainers/community/contributor-growth-framework/pr-workflow.md @@ -7,58 +7,58 @@ description: > Develop a welcoming pull request workflow that sets contributors up for success. --- -The PR workflow is at the core of code contributions. Make sure it's a smooth experience, automate as much as possible (bots can be really helpful), and try to get contributors to contribute something else after successfully submitting a PR. +The PR workflow is at the core of code contributions. Make sure it's a smooth experience, automate as much as possible (bots can be really helpful), and try to get contributors to contribute something else after successfully submitting a PR. -Here's a typical PR workflow: - 1. **User opens an issue** (bug or feature request): As maintainers, you will first troubleshoot the bug or review the feature request. Reach out to the submitter to thank them for the issue and assess if they want to be involved. If they are, ask them to continue the conversation on your contributor channel. For vulnerabilities, projects should adopt the processes outlined by [TAG Security](https://github.com/cncf/tag-security/tree/main/project-resources), so that projects can accept security reports privately and address them before they are disclosed publicly. +Here's a typical PR workflow: + 1. **User opens an issue** (bug or feature request): As maintainers, you will first troubleshoot the bug or review the feature request. Reach out to the submitter to thank them for the issue and assess if they want to be involved. If they are, ask them to continue the conversation on your contributor channel. For vulnerabilities, projects should adopt the processes outlined by [TAG Security](https://github.com/cncf/tag-security/tree/main/community/resources/project-resources), so that projects can accept security reports privately and address them before they are disclosed publicly. - 2. **Pick conversation up on contributor channel**: -Consider assigning new contributors to a mentor or point of contact who can follow up making sure they remain motivated and follow through (may not always be possible due to time constraints). Community CRMs will help you keep track of contributor activity. If you don't see any activity from your prospective contributor, check-in to see if they are still interested. A gentle reminder may revive their motivation and show them you really care about their contribution. + 2. **Pick conversation up on contributor channel**: +Consider assigning new contributors to a mentor or point of contact who can follow up making sure they remain motivated and follow through (may not always be possible due to time constraints). Community CRMs will help you keep track of contributor activity. If you don't see any activity from your prospective contributor, check-in to see if they are still interested. A gentle reminder may revive their motivation and show them you really care about their contribution. - 3. **Submit one PR**: Once they submitted their PR, suggest another contribution or, if they have been contributing for a while, ask them if they'd like to take the next step and move up the contributor ladder. + 3. **Submit one PR**: Once they submitted their PR, suggest another contribution or, if they have been contributing for a while, ask them if they'd like to take the next step and move up the contributor ladder. -This is really key. If you want people to engage more or take on more responsibility, you have to encourage them to do so. It's a little bit like a career coach (don't forget to take notes in your community CRM about their preferences, time restrictions, etc. Having that info at hand will prove useful during future conversations). While guiding people is a lot of work and you may think you don't have time to do so, it will save you a lot of time down the line. +This is really key. If you want people to engage more or take on more responsibility, you have to encourage them to do so. It's a little bit like a career coach (don't forget to take notes in your community CRM about their preferences, time restrictions, etc. Having that info at hand will prove useful during future conversations). While guiding people is a lot of work and you may think you don't have time to do so, it will save you a lot of time down the line. -## Manage Expectations +## Manage Expectations -Contributors, especially seasoned ones, can get really impatient after submitting their PR. Generally, you should try to turn around reviews quickly, especially if it's their first PR. But volume can be an issue. So, if it will take some time, setting clear expectations will help avoid frustrations on both sides. +Contributors, especially seasoned ones, can get really impatient after submitting their PR. Generally, you should try to turn around reviews quickly, especially if it's their first PR. But volume can be an issue. So, if it will take some time, setting clear expectations will help avoid frustrations on both sides. -What should you communicate prior to a PR: +What should you communicate prior to a PR: - ***Average response time***, especially for small teams that don't have the bandwidth to respond quickly. When wait time is particularly long, explain why. Don't wait for them to make assumptions about why things aren't moving forward. Also remind them that open source work is often done during free time outside of regular working hours. + ***Average response time***, especially for small teams that don't have the bandwidth to respond quickly. When wait time is particularly long, explain why. Don't wait for them to make assumptions about why things aren't moving forward. Also remind them that open source work is often done during free time outside of regular working hours. - ***Clearly describe flow and action items***, whether a design doc or follow-up questions are part of the submission process, set the expectations for what all the steps are and how long it will take. + ***Clearly describe flow and action items***, whether a design doc or follow-up questions are part of the submission process, set the expectations for what all the steps are and how long it will take. -What should you communicate after opening a PR: - - ***Expectation about code and documentation quality***. To avoid unnecessary back and forth dialog as well as lengthy discussions, leverage automated PR checks. This will help you avoid a lot of headaches and also declaratively defines expectations for PRs. +What should you communicate after opening a PR: - ***Capture PR follow-up ideas***. During the process, you may identify something that isn't necessarily related to the current PR. Add a comment, like "I see you hardcoded this here and would love to see it configurable by environment variables. Could you submit an issue so we remember to work on it and merge it with this PR?" This is also a great way of building trust and goodwill with a potential long-term contributor or maintainer. + ***Expectation about code and documentation quality***. To avoid unnecessary back and forth dialog as well as lengthy discussions, leverage automated PR checks. This will help you avoid a lot of headaches and also declaratively defines expectations for PRs. + + ***Capture PR follow-up ideas***. During the process, you may identify something that isn't necessarily related to the current PR. Add a comment, like "I see you hardcoded this here and would love to see it configurable by environment variables. Could you submit an issue so we remember to work on it and merge it with this PR?" This is also a great way of building trust and goodwill with a potential long-term contributor or maintainer. Where or how do you communicate all this? Leverage GitHub issue templates and bots as much as possible. -Loop contributors into issues when you know that they are interested in that particular area, this is powerful for introducing community members. If you use a community CRM, create tags so you can quickly search for relevant contributors. This will show them that you value their input and opinion. +Loop contributors into issues when you know that they are interested in that particular area, this is powerful for introducing community members. If you use a community CRM, create tags so you can quickly search for relevant contributors. This will show them that you value their input and opinion. ## Providing Sufficient Contributor Tools -To incentivize contributions, you need more than just a contributor guide; you need a toolkit. But don't overdo it. If you have too many resources, you may overwhelm them. Here are a few examples. Identify what makes most sense for your project and what you'll be able to maintain (and retire old material to avoid confusion). +To incentivize contributions, you need more than just a contributor guide; you need a toolkit. But don't overdo it. If you have too many resources, you may overwhelm them. Here are a few examples. Identify what makes most sense for your project and what you'll be able to maintain (and retire old material to avoid confusion). - * Comprehensive docs - * PR checklist - * Templates - * Hello World + * Comprehensive docs + * PR checklist + * Templates + * Hello World * Code walkthroughs (videos, docs, etc.) * [Contributor ladder] - * "A day in the life of a maintainer" description + * "A day in the life of a maintainer" description -***On demand videos:*** Contributing 101, guideline videos. These can be served through [automated bots](https://github.com/hoodiehq/first-timers-bot) (e.g. "hey, I see you are a first-time contributor. Check out this video on how to successfully submit a PR"). +***On demand videos:*** Contributing 101, guideline videos. These can be served through [automated bots](https://github.com/hoodiehq/first-timers-bot) (e.g. "hey, I see you are a first-time contributor. Check out this video on how to successfully submit a PR"). -***New contributor workshops:*** This also makes maintainers more comfortable with them contributing +***New contributor workshops:*** This also makes maintainers more comfortable with them contributing [Contributor ladder]: https://github.com/cncf/project-template/blob/main/CONTRIBUTOR_LADDER.md -## Automate as much as you can +## Automate as much as you can -Automation is great and you should use it wherever possible. The Kubernetes project leverages a lot of bots. From ensuring issues are properly labeled to guiding contributors towards a successful PR. But beware, if you use too many bots people will start ignoring them no matter how useful the info they provide. A balanced, strategic approach is key. Also, don't forget that automation is a great way for people to be involved with the project by helping to build or document the infrastructure that makes your project work. +Automation is great and you should use it wherever possible. The Kubernetes project leverages a lot of bots. From ensuring issues are properly labeled to guiding contributors towards a successful PR. But beware, if you use too many bots people will start ignoring them no matter how useful the info they provide. A balanced, strategic approach is key. Also, don't forget that automation is a great way for people to be involved with the project by helping to build or document the infrastructure that makes your project work. -The Kubernetes project uses [prow](https://github.com/kubernetes/test-infra/tree/master/prow), a CI/CD tool written for Kubernetes handling a lot of the configuration of the workflow bots. It does have quite a bit of maintenance overhead and there are certainly more lightweight solutions such as GitHub apps and [GitHub Actions](https://github.com/actions). [Derek](https://github.com/alexellis/derek) handles labeling issues as well as closing issues or assigning them to other people. +The Kubernetes project uses [prow](https://github.com/kubernetes/test-infra/tree/master/prow), a CI/CD tool written for Kubernetes handling a lot of the configuration of the workflow bots. It does have quite a bit of maintenance overhead and there are certainly more lightweight solutions such as GitHub apps and [GitHub Actions](https://github.com/actions). [Derek](https://github.com/alexellis/derek) handles labeling issues as well as closing issues or assigning them to other people. diff --git a/website/content/maintainers/security/security-guidelines.md b/website/content/maintainers/security/security-guidelines.md index e51a0bb9..297f2196 100644 --- a/website/content/maintainers/security/security-guidelines.md +++ b/website/content/maintainers/security/security-guidelines.md @@ -66,7 +66,7 @@ We recommend that any change to the repository should be introduced as part of a ### Issue template -Any ideas, bugs or enhancement suggestions reported to the project need to be tracked, and can then be discussed, triaged and prioritized/de-prioritized for implementation. GitHub Issues are one such avenue that allows tracking and managing ideas until they are brought to fruition. We recommend the following template for proposing changes to the project [CNCF TAG Security Project Resouces - Issue Template](https://github.com/cncf/tag-security/blob/main/project-resources/templates/ISSUE_TEMPLATE.md). +Any ideas, bugs or enhancement suggestions reported to the project need to be tracked, and can then be discussed, triaged and prioritized/de-prioritized for implementation. GitHub Issues are one such avenue that allows tracking and managing ideas until they are brought to fruition. We recommend the following template for proposing changes to the project [CNCF TAG Security Project Resources - Issue Template](https://github.com/cncf/tag-security/blob/main/community/resources/project-resources/templates/ISSUE_TEMPLATE.md). ### Commit signing @@ -105,13 +105,13 @@ Self-assessment dives into the following aspects of the project to understand th 7. Secure development practices 8. Resolving security issues -A template to perform the self assessment is available at [CNCF TAG Security Project Resouces - Self-assessment](https://github.com/cncf/tag-security/blob/main/assessments/guide/self-assessment.md). All the assessments (self-assessment and joint assessment) conducted by TAG Security can be found at TAG Security GitHub repository. As an example, self assessments are available within the dedicated project folders at [Assessments folder of the CNCF TAG Security GitHub repository](https://github.com/cncf/tag-security/tree/main/assessments/projects). Further sections (SECURITY.md in particular) in this document provide some of the pointers to address the gaps and create the necessary process & documentation. +A template to perform the self assessment is available at [CNCF TAG Security Project Resources - Self-assessment](https://github.com/cncf/tag-security/blob/main/assessments/guide/self-assessment.md). All the assessments (self-assessment and joint assessment) conducted by TAG Security can be found at TAG Security GitHub repository. As an example, self assessments are available within the dedicated project folders at [Assessments folder of the CNCF TAG Security GitHub repository](https://github.com/cncf/tag-security/tree/main/assessments/projects). Further sections (SECURITY.md in particular) in this document provide some of the pointers to address the gaps and create the necessary process & documentation. ## 3. SECURITY.md Awareness and processes are a big part of enforcing security in any project. A SECURITY.md file in your repository should talk about the security considerations of the project, and the efforts undertaken to ensure that there are policies and processes in place to report vulnerabilities to the project maintainers, and for project maintainers to notify the community of the status of the vulnerabilities. It should also list the dedicated personnel responsible to address these vulnerabilities in a timely manner. In GitHub, the SECURITY.md file creates a security policy, and when someone creates an issue in your repository, they will see a link to your project's security policy. Further information regarding security policy is available at [GitHub Docs - Adding a security policy to your repository](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository). -CNCF Technical Advisory Group for Security maintains a number of templates to assist projects in addressing these sections, which can be found at [CNCF TAG Security GitHub repository, under Project Resouces folder](https://github.com/cncf/tag-security/tree/main/project-resources). A special thank you to Google's OSS vulnerability guide folks for making the Security TAG aware of this collection of resources upon which much of this content was built on. +CNCF Technical Advisory Group for Security maintains a number of templates to assist projects in addressing these sections, which can be found at [CNCF TAG Security GitHub repository, under Project Resources folder](https://github.com/cncf/tag-security/tree/main/community/resources/project-resources). A special thank you to Google's OSS vulnerability guide folks for making the Security TAG aware of this collection of resources upon which much of this content was built on. Disclaimer: These resources are designed to be helpful to projects and organizations, they require customization and configuration by the project intending to use them. It does not prevent security issues from being found in a project, will not automatically resolve them, and does not place CNCF Security TAG as the responsible party. If changes are made to these templates, projects are not required to pull in a new update. @@ -121,7 +121,7 @@ This document is an outcome of the self-assessment which articulates all the mea ## 3.2 Security contacts -This document states who are the personnel to reach out to in case of any security questions regarding the project, including but not limited to the triaging and handling of incoming security issues or security reports. Security contacts could be external participants and are not limited to being the maintainers of the projects. A template for this document is available at [CNCF TAG Security Project Resouces - Security Contacts](https://github.com/cncf/tag-security/blob/main/project-resources/templates/SECURITY_CONTACTS.md) +This document states who are the personnel to reach out to in case of any security questions regarding the project, including but not limited to the triaging and handling of incoming security issues or security reports. Security contacts could be external participants and are not limited to being the maintainers of the projects. A template for this document is available at [CNCF TAG Security Project Resources - Security Contacts](https://github.com/cncf/tag-security/blob/main/community/resources/project-resources/templates/SECURITY_CONTACTS.md) **NOTE** @@ -131,7 +131,7 @@ CNCF could help create a mailing address (through service desk ticket) should pr Vulnerabilities are sensitive information and exposure of information regarding vulnerabilities without the availability of a patch generates unintended risk for all the consumers of this project, hence it should be handled with caution. -At a minimum, the vulnerability reporting policy projects should include is as follows, A template for this document is available at [CNCF TAG Security Project Resouces - Reporting a Vulnerability](https://github.com/cncf/tag-security/blob/main/project-resources/templates/SECURITY.md#reporting-a-vulnerability): +At a minimum, the vulnerability reporting policy projects should include is as follows, A template for this document is available at [CNCF TAG Security Project Resources - Reporting a Vulnerability](https://github.com/cncf/tag-security/blob/main/community/resources/project-resources/templates/SECURITY.md#reporting-a-vulnerability): 1. The medium to report vulnerabilities - Email, Web form etc. 2. Disclosure timeline @@ -153,7 +153,7 @@ The vulnerabilities reported to the project are then handled by the security poi 5. The consequences of any violations 6. Disclosure timeline -A template for this document is available at [CNCF TAG Security Project Resouces - Embargo Policy](https://github.com/cncf/tag-security/blob/main/project-resources/templates/embargo-policy.md) +A template for this document is available at [CNCF TAG Security Project Resources - Embargo Policy](https://github.com/cncf/tag-security/blob/main/community/resources/project-resources/templates/embargo-policy.md) ## 3.5 Security notifications @@ -169,7 +169,7 @@ The vulnerabilities may need to be reported to certain stakeholders, and for thi 8. Timeline of events associated with this notification 9. Any additional information relevant for this notification -A template for this notification is available at [CNCF TAG Security Project Resouces - Embargo](https://github.com/cncf/tag-security/blob/main/project-resources/templates/embargo.md) +A template for this notification is available at [CNCF TAG Security Project Resources - Embargo](https://github.com/cncf/tag-security/blob/main/community/resources/project-resources/templates/embargo.md) ## 4. Incident Response @@ -189,7 +189,7 @@ Incidence response primarily states how the vulnerability is triaged, replicated 1. If a CVE is already present, request the CVE 4. Patch publication and Notification -In addition to the above, you could also consider adding relevant timelines, including but not limited to third party disclosure timelines. A template for the incident management process is available at [CNCF TAG Security Project Resouces - Incident Response](https://github.com/cncf/tag-security/blob/main/project-resources/templates/incident-response.md) +In addition to the above, you could also consider adding relevant timelines, including but not limited to third party disclosure timelines. A template for the incident management process is available at [CNCF TAG Security Project Resources - Incident Response](https://github.com/cncf/tag-security/blob/main/community/resources/project-resources/templates/incident-response.md) ## 5. OpenSSF best practices badging diff --git a/website/content/maintainers/templates/_index.md b/website/content/maintainers/templates/_index.md index 52232376..aac471d6 100644 --- a/website/content/maintainers/templates/_index.md +++ b/website/content/maintainers/templates/_index.md @@ -11,7 +11,7 @@ aliases: --- We have a [project template] repository that has templates for everything your project needs -to get started and eventually join the CNCF. +to get started and eventually join the CNCF. ## Getting Started @@ -20,13 +20,13 @@ but we also have how-to guides here on the website that are a better place to start if you haven't used a particular template before. Please note that the security templates may be found in the -[Security TAG's project resources folder](https://github.com/cncf/tag-security/tree/main/project-resources). +[Security TAG's project resources folder](https://github.com/cncf/tag-security/tree/main/community/resources/project-resources). ### Customize Templates Each template contains instructions to customize the contents for your project. Most files use comments with TODO to call out where you need to make changes. We recommend -viewing the files in raw or text form so that you can see the comments. +viewing the files in raw or text form so that you can see the comments. For example in markdown files, we use `` to provide additional guidance or indicate where action is required but you won't see those comments diff --git a/website/content/maintainers/templates/governance-elections.md b/website/content/maintainers/templates/governance-elections.md index 0b357bd5..b7ba4cde 100644 --- a/website/content/maintainers/templates/governance-elections.md +++ b/website/content/maintainers/templates/governance-elections.md @@ -97,14 +97,14 @@ on exactly how your project plans to operate: ### What Do I Need to Customize? -All sections of this template will likely need to be customized, so we recommend +All sections of this template will likely need to be customized, so we recommend that you review the [Knative Steering Committee](https://github.com/knative/community/blob/main/STEERING-COMMITTEE.md) as an example of how to customize this template. ### What Else Is Required? -This template assumes that you have already adopted the [Code of Conduct], -added the CNCF-required [security practices], and added a [Scope section](../governance/charter/) to your README. +This template assumes that you have already adopted the [Code of Conduct], +added the CNCF-required [security practices], and added a [Scope section](../governance/charter/) to your README. It assumes that you are using the [Contributor Ladder], since it is a good way to provide guidance about eligibility requirements. It is possible to implement this without a @@ -116,7 +116,7 @@ guidance about eligibility requirements. It is possible to implement this withou **Steering Committee**: The overall governing body for your project, and the list of maintainers by CNCF definition. -**Maintainers**: The actual approvers/technical leadership of the project, which might be different from the membership of the Steering Committee. +**Maintainers**: The actual approvers/technical leadership of the project, which might be different from the membership of the Steering Committee. **CNCF Maintainers**: The list of "maintainers" per CNCF rules, as in people who are allowed to make decisions for the project that the CNCF will carry out. In a Steering Committee project, this is the Steering Committee instead of the list of approvers. @@ -208,8 +208,8 @@ transition period, but plan to have staggered 2-year terms, we recommend that fo the first year of the Steering Committee half of the seats should be elected for a 1-year term, and the other half should be elected for a 2-year term. -While not recommended, an alternative to staggered terms is that you can -have all of the members elected at the same time to serve for a specified term. +While not recommended, an alternative to staggered terms is that you can +have all of the members elected at the same time to serve for a specified term. This can introduce hardship on the newly elected members attempting to pick-up where the previous Committee left off if there is no formal overlap or handoff. @@ -234,8 +234,8 @@ approver in one or more OWNERS files, or similar. **Voting Procedure** -For most elections, we recommend using -[Condorcet](https://en.wikipedia.org/wiki/Condorcet_method) ranking +For most elections, we recommend using +[Condorcet](https://en.wikipedia.org/wiki/Condorcet_method) ranking using the IRV method as specified in the template. [Elekto](https://elekto.dev/), [OpaVote](https://www.opavote.com/), and [Helios](https://vote.heliosvoting.org/) are all options for running an election. @@ -278,6 +278,6 @@ needs. Recommended text can be found in the template. [TAG Contributor Strategy]: https://github.com/cncf/tag-contributor-strategy [Contributor Ladder]: https://github.com/cncf/project-template/blob/main/CONTRIBUTOR_LADDER.md [Code of Conduct]: https://github.com/cncf/project-template/blob/main/CODE_OF_CONDUCT.md -[security practices]: https://github.com/cncf/tag-security/tree/main/project-resources +[security practices]: https://github.com/cncf/tag-security/tree/main/community/resources/project-resources [Lazy Consensus]: https://community.apache.org/committers/lazyConsensus.html [Charters]: [/maintainers/governance/charter/] diff --git a/website/content/maintainers/templates/governance-maintainer.md b/website/content/maintainers/templates/governance-maintainer.md index 3e03d40d..73475910 100644 --- a/website/content/maintainers/templates/governance-maintainer.md +++ b/website/content/maintainers/templates/governance-maintainer.md @@ -13,8 +13,8 @@ aliases: | Maintainers | Contributors | Yes, graduated | -This HowTo is for project maintainers who need Governance documentation for their project. -The goal of a GOVERNANCE.md file is to inform contributors about how your +This HowTo is for project maintainers who need Governance documentation for their project. +The goal of a GOVERNANCE.md file is to inform contributors about how your project is run, and encourage them to get involved in project leadership. Great governance docs will: @@ -41,9 +41,9 @@ When you finish editing the template, remove the Instruction links that explain # Maintainer Council Governance [Maintainer Council] is the most basic formal governance for projects, and as -such used by more projects than any other. TAG Contributor Stategy developed it to cover -a very common circumstance, where the overlap of repository approvers and -people who handle other governance issues is 100%. It was originally based on +such used by more projects than any other. TAG Contributor Stategy developed it to cover +a very common circumstance, where the overlap of repository approvers and +people who handle other governance issues is 100%. It was originally based on the governance of the [Jaeger project]. This template defines a simple structure where the project Maintainers perform @@ -60,14 +60,14 @@ The [Maintainer Council] template is for you if your project: If you have a relatively uncomplicated project with a small pool of contributors -- like the vast majority of Cloud Native projects -- Maintainer Council is -probably for you. It's even appropriate for a project that will eventually need a more +probably for you. It's even appropriate for a project that will eventually need a more complex governance, but does not need or want it yet. ## Requirements ### What Do I Need To Know? -This simple template really only requires you to know a few things about how +This simple template really only requires you to know a few things about how your project actually works, today. These are: * A list of your current maintainers @@ -90,7 +90,7 @@ See the section details below for notes on how you're likely to customize them. ### What Else Is Required? -This template assumes that you have already adopted the [Code of Conduct], +This template assumes that you have already adopted the [Code of Conduct], added the CNCF-required [security practices], and added a [Scope section](../governance/charter/) to your README. If you have not yet, you will need to do that as well. This template does not assume that you are using the [Contributor Ladder], although doing so is recommended. @@ -99,7 +99,7 @@ to do that as well. This template does not assume that you are using the **Project**: Your entire CNCF project, rather than individual repositories or subprojects. -**Maintainer**: Someone who is both a Project Maintainer for CNCF purposes, and +**Maintainer**: Someone who is both a Project Maintainer for CNCF purposes, and is an approver for critical parts of the project. **Maintainer Council**: the collective group of all project Maintainers. @@ -119,17 +119,17 @@ See our documentation on [Charters](../governance/charter/) for some examples. ### Maintainers -This section outlines the definition and responsibilities of a Maintainer, +This section outlines the definition and responsibilities of a Maintainer, which in this governance is identical to being a merge approver (also known as a "committer"). Since your Maintainers are the only authority in the project, it is critical to document how that authority is earned. -Your Maintainers should customize the list of requirements to become a Maintainer +Your Maintainers should customize the list of requirements to become a Maintainer with requirements that match their actual qualifications. It's better if you can define -a path for substantial non-code contributors, such as documentation leads and -community managers, to also become Maintainers. +a path for substantial non-code contributors, such as documentation leads and +community managers, to also become Maintainers. -If you have a separate, full [Contributor Ladder], you will want to cut this +If you have a separate, full [Contributor Ladder], you will want to cut this list of requirements and refer to that document instead. This section covers both how new Maintainers are selected, and how existing Maintainers @@ -139,10 +139,10 @@ when Maintainers move on to other things. ### Meetings You need to explicitly describe the venues at which official project decisions -get made. This may happen at a public weekly developer meeting, through GitHub +get made. This may happen at a public weekly developer meeting, through GitHub issues and PRs, on a mailing list, or all of those. This is both so that contributors know where to go with requests, and so that they are reassured that important -project decisions will not happen in the private meeting rooms of any Maintainers' +project decisions will not happen in the private meeting rooms of any Maintainers' employer. As such, you may need to modify this section to cover your actual communications @@ -151,13 +151,13 @@ channels. ### CNCF Resources This covers one of the powers of Maintainers, which is that they can ask the -CNCF to do things for the project. This outlines one possible process for this +CNCF to do things for the project. This outlines one possible process for this to happen, based on community meetings. If you prefer to handle this by GitHub instead, the language would be something like this: ``` Any Maintainer may suggest a request for CNCF resources, by filing an issue in -the [community repo](TODO:main or /community repository URL). A simple majority +the [community repo](TODO:main or /community repository URL). A simple majority of Maintainers approves the request. The Maintainers may also choose to delegate working with the CNCF to non-Maintainer community members, who will then be added to the [CNCF's Maintainer List](https://github.com/cncf/foundation/blob/main/project-maintainers.csv) @@ -173,7 +173,7 @@ instead: ``` [Code of Conduct](./code-of-conduct.md) -violations by community members will be referred to the CNCF Code of Conduct +violations by community members will be referred to the CNCF Code of Conduct Committee. Should the CNCF CoC Committee need to work with the project on resolution, the Maintainers will appoint a non-involved contributor to work with them. ``` @@ -187,12 +187,12 @@ to the Maintainers Council. Vulnerability reports can be handled by the Maintainers, or they can delegate that responsibility to a smaller team. The language given here covers both possibilities, but your project will need to decide which practice they will follow. You will -also need to create your security response documents using the +also need to create your security response documents using the [templates from TAG-Security][security practices]. ### Voting -This clause defines how votes are held and counted, in order not to repeat that +This clause defines how votes are held and counted, in order not to repeat that information several times in the document. First, it asserts that most "voting" is informal, using what is called [Lazy Consensus]. @@ -203,34 +203,34 @@ three different reasons why you would take an actual vote: 1. There is expressed disagreement on the issue 2. The action is something major and even irreversible for the project, so that you want to be extra-sure that every Maintainer is aware of it -3. The decision is something covered in GOVERNANCE.md as requiring a vote, +3. The decision is something covered in GOVERNANCE.md as requiring a vote, such as adding or removing a Maintainer The text assumes that most voting happens on a Maintainer or developer -mailing list and public meetings. Some projects prefer to handle votes via GitHub +mailing list and public meetings. Some projects prefer to handle votes via GitHub issues. If this is your project's practice, change the text here to refer to GitHub, for example: - + ``` A vote can be taken by filing a GitHub issue labeled with "VOTE". The issue will -be open until a majority of Maintainers vote for or against it, at which point +be open until a majority of Maintainers vote for or against it, at which point it will be closed. ``` The overall principle employed here is that every vote requires counting against the number of Maintainers who exist, rather than which Maintainers are participating -in the vote. For example, if your project had 8 maintainers and you were voting on -a design proposal, and six maintainers participated in the vote, five of them would -need to approve it, rather than four, since five is the majority of all Maintainers. - -The advantage of this approach is that your project can be extremely flexible about -where and how votes are held since there's little danger of deliberate exclusion. -If you instead want to hold votes based on a count of participants, you'll need -to be very prescriptive about where votes can be held, what notice is required, +in the vote. For example, if your project had 8 maintainers and you were voting on +a design proposal, and six maintainers participated in the vote, five of them would +need to approve it, rather than four, since five is the majority of all Maintainers. + +The advantage of this approach is that your project can be extremely flexible about +where and how votes are held since there's little danger of deliberate exclusion. +If you instead want to hold votes based on a count of participants, you'll need +to be very prescriptive about where votes can be held, what notice is required, and how long they need to be open. -We also advise reserving 2/3 votes to things that require substantial deliberation, -such as removing a maintainer or changing the charter. Otherwise, routine project +We also advise reserving 2/3 votes to things that require substantial deliberation, +such as removing a maintainer or changing the charter. Otherwise, routine project business can get blocked simply by people being on vacation. [GOVERNANCE-maintainer.md template]: https://github.com/cncf/project-template/blob/main/GOVERNANCE-maintainer.md @@ -239,6 +239,6 @@ business can get blocked simply by people being on vacation. [Jaeger project]: https://github.com/jaegertracing/jaeger/blob/main/GOVERNANCE.md [Contributor Ladder]: https://github.com/cncf/project-template/blob/main/CONTRIBUTOR_LADDER.md [Code of Conduct]: https://github.com/cncf/project-template/blob/main/CODE_OF_CONDUCT.md -[security practices]: https://github.com/cncf/tag-security/tree/main/project-resources +[security practices]: https://github.com/cncf/tag-security/tree/main/community/resources/project-resources [Lazy Consensus]: https://community.apache.org/committers/lazyConsensus.html [Charter]: [/maintainers/governance/charter/] diff --git a/website/content/maintainers/templates/governance-subprojects.md b/website/content/maintainers/templates/governance-subprojects.md index 9f12efb4..cb51a627 100644 --- a/website/content/maintainers/templates/governance-subprojects.md +++ b/website/content/maintainers/templates/governance-subprojects.md @@ -38,7 +38,7 @@ When you finish editing the template, remove the Instruction links that explain # Governance By Subprojects -[Subproject Governance] is the most complex of our templates, since it covers +[Subproject Governance] is the most complex of our templates, since it covers the most complex situation: a "federated" project that consists of multiple, related, but quasi-autonomous subprojects. The TAG developed it originally for the [Konveyor] project, and has been used by several since then, including @@ -46,12 +46,12 @@ the [Operator Framework] project. By "subprojects", we mean technically distinct areas of your overall project that each have their own internal leadership and operations. Depending on your -history, you may call these subprojects, projects, SIGs, vendors, plugins, +history, you may call these subprojects, projects, SIGs, vendors, plugins, drivers, or a variety of other labels. We will use "subprojects" as a generic label. -This template defines a two-level structure where authority flows up from the -contributors to the subprojects, to subproject leadership, and from them to +This template defines a two-level structure where authority flows up from the +contributors to the subprojects, to subproject leadership, and from them to overall project leadership. ## Is This Template for Us? @@ -62,13 +62,13 @@ The [Subproject Governance] template is for you if your project: 2. The different subprojects share few or no maintainers 3. The overall pool of maintainers is too large or too differentiated for all maintainers to participate directly in overall project governance - + If your project meets all of the above conditions, or expects to do so soon, governance by subproject may be for you. -If you don't yet meet these conditions, we recommend that you start with a -simpler governance template, like the [Maintainer Council] template, and move to -this subprojects template later when you actually need it. Starting with +If you don't yet meet these conditions, we recommend that you start with a +simpler governance template, like the [Maintainer Council] template, and move to +this subprojects template later when you actually need it. Starting with a complicated governance structure before you need it creates overhead and extra work for project members and maintainers whose time is often better spent on project development, rather than governance. @@ -81,32 +81,32 @@ In addition to the general requirement to research how organization, task assignment, and authority in your project already works, there are some specific research requirements for this template: -* What are your subprojects, currently? How many are there? How do things like +* What are your subprojects, currently? How many are there? How do things like documentation and website development fit into your list of subprojects? * How are leaders/maintainers selected in each subproject? What are the requirements to be a maintainer? Is this the same across all subprojects, or different? -* What does each subproject "own"? Do they have separate repositories, or do +* What does each subproject "own"? Do they have separate repositories, or do they share repos? Take your time answering these questions. Particularly, determining the list -of subprojects can be harder than you expect. For example, you can pretty -easily decide that each "working group" in your project is a subproject, -but what about documentation? Does each subproject own its own docs, +of subprojects can be harder than you expect. For example, you can pretty +easily decide that each "working group" in your project is a subproject, +but what about documentation? Does each subproject own its own docs, or is there a "documentation" subproject? What about general project -administration, like github management, events, and your website? Is that +administration, like github management, events, and your website? Is that a subproject, or is it handled some other way? ### What Do I Need to Customize? Most customization of Subprojects happens in the following areas: -* Names: the template uses Project/Subproject. However, many CNCF projects - already have other terms for these concepts, such as Project/SIG or +* Names: the template uses Project/Subproject. However, many CNCF projects + already have other terms for these concepts, such as Project/SIG or Umbrella/Project, and you will need to do a search-and-replace. * Values: like all templates, you need to have a list of project values to include. * Individual Subproject Governance: the template assumes that each subproject - is governed by a maintainer council. Should you have different + is governed by a maintainer council. Should you have different governance within subprojects, you will need to detail that. * Whether elected as well as appointed members should serve on the Steering Committee, and how many. @@ -117,8 +117,8 @@ it. ### What Else Is Required? -This template assumes that you have already adopted the [Code of Conduct](https://github.com/cncf/project-template/blob/main/CODE_OF_CONDUCT.md), -added the CNCF-required [security practices](https://github.com/cncf/tag-security/tree/main/project-resources), and added a [Scope section](../governance/charter/) to your README. +This template assumes that you have already adopted the [Code of Conduct](https://github.com/cncf/project-template/blob/main/CODE_OF_CONDUCT.md), +added the CNCF-required [security practices](https://github.com/cncf/tag-security/tree/main/community/resources/project-resources), and added a [Scope section](../governance/charter/) to your README. The template also expects you to have a documented [Contributor Ladder], either based on our template or otherwise. If you do not, you will need to adopt that @@ -129,15 +129,15 @@ as well. **Project**: The overall, "umbrella", "core", or "main" project **Subproject**: The individual group/repository where work on the project gets done; -alternately called projects, SIGs, repos, drivers, plugins, operators, working +alternately called projects, SIGs, repos, drivers, plugins, operators, working groups, or other units of work that each have their own maintainers. **Maintainer**: A Maintainer of any individual Subproject; the highest level on the Contributor Ladder. Also called "owner" or "approver". **Contributor**: Anyone who contributes significantly to your project, whether -code or non-code, according to the membership threshold defined in your -contributor ladder. Called "Organization Member" in the [Contributor Ladder]. +code or non-code, according to the membership threshold defined in your +contributor ladder. Called "Organization Member" in the [Contributor Ladder]. Inclusive of the Maintainers. ## Template Details @@ -170,27 +170,27 @@ the form of: * [Subproject Name](link): short definition of this subproject ``` -The name of the subproject should link to the "main" repository or subfolder +The name of the subproject should link to the "main" repository or subfolder of that subproject, where hopefully there is additional information about that subproject. Example: ``` -* [Documentation](https://github.com/ourproject/docs/): writes, edits, and owns +* [Documentation](https://github.com/ourproject/docs/): writes, edits, and owns the User Guide, Administrator Guide, and the project blog. ``` This is then followed by an explanation of how each subproject is governed. The example provided offers a simple maintainer committee structure which you'll -notice is very similar to the [Maintainer Council] governance option for +notice is very similar to the [Maintainer Council] governance option for projects. This relies on having a complete [Contributor Ladder], which avoids needing to define maintainers and other roles in the governance document itself. If the term you use for your highest level of technical responsibility is not "maintainer", you'll want to replace that in this section. -If your subprojects already have leadership structures that are +If your subprojects already have leadership structures that are different from this, you'll need to define them here, or in linked document(s). In addition to any details those subproject documents may have, you'll need to ensure that they also cover the following overall project governance @@ -205,12 +205,12 @@ or one that expects to grow to 4 or more subprojects. However, if your project has 2 to 4 subprojects and does not expect to grow, then it may be appropriate to have each subproject appoint two representatives. -If you feel that selection of the representative is likely to be contentious, +If you feel that selection of the representative is likely to be contentious, you may wish to change to using a preference election system over simple polling. ### Steering Committee -The Steering Committee (SC) is the escalation-level body in charge of the overall +The Steering Committee (SC) is the escalation-level body in charge of the overall project. This body might also be called the Technical Oversight Committee. The members of the SC are the project's owners as far as the CNCF is concerned, and are responsible for the running of the overall project. @@ -218,7 +218,7 @@ and are responsible for the running of the overall project. There are a list of suggested duties for SC members, which should be edited to reflect your actual project's needs. Also, note that the template suggests that the SC can delegate its powers to individuals or other groups, which -will be a necessity for any large project. For example, the SC could +will be a necessity for any large project. For example, the SC could delegate handling security reports to a Security Team. In most projects, the day to day technical decisions are handled within each subproject, but conflicts between subprojects or anything else that can't be handled within a subproject @@ -226,19 +226,19 @@ can be escalated to the Steering Committee. ### Elections -The template includes text for elected members comprising a minority -of the Steering Committee. Our recommendation is to have zero, one, +The template includes text for elected members comprising a minority +of the Steering Committee. Our recommendation is to have zero, one, or two of these, but not more. The reasons for having these are: -* Helps balance out big vs. small subprojects without having designated numbers +* Helps balance out big vs. small subprojects without having designated numbers of extra seats for specific subprojects * Gives your general contributors some direct representation * Offers a route to leadership for folks outside of slowly working through the Contributor Ladder * Gets contributors to think about striving for leadership roles once a year - + However, federated projects can work quite well without elected seats, especially if the overall pool of contributors is small and inclined to consensus. Elections do involve a significant amount of overhead. If you decide to do without them, @@ -248,13 +248,13 @@ of the Steering section. If you are holding elections, the process described is a simplifed version of the process used by Kubernetes. That project has found the appointment of Election Officers by the SC to be a good way to handle conducting elections. -For the elections themselves, the CNCF can provide Elekto instances for +For the elections themselves, the CNCF can provide Elekto instances for holding the vote, or you may have another preference such as Helios or OpaVote. -The template text outlines only one type of representative: a general +The template text outlines only one type of representative: a general contributor Member representative. Eligibility to vote would be qualifiying for the "Organization Member" level on our template [Contributor Ladder], or -whatever your project equivalent is. +whatever your project equivalent is. Depending on your project's needs, you may want to have alternative or additional types of representatives. For example, you might want to have a representative @@ -264,18 +264,18 @@ would be: ``` The Maintainer Representative(s) will be elected by the collective Maintainers -of all subprojects, as defined in the Contributor Ladder. They will be elected +of all subprojects, as defined in the Contributor Ladder. They will be elected annually. ``` -In the current text, candidates are not required to be Organization Members -or Maintainers themselves. You may or may not want to require that. If you +In the current text, candidates are not required to be Organization Members +or Maintainers themselves. You may or may not want to require that. If you do, use text like: ``` The Contributor Representative(s) will be elected by the collective Organization -Members of all subprojects, as defined in the Contributor Ladder. -Representative(s) must be Organization Members themselves, and will be elected +Members of all subprojects, as defined in the Contributor Ladder. +Representative(s) must be Organization Members themselves, and will be elected annually. ``` @@ -290,10 +290,10 @@ to staff a CoCC outside of the SC. If you do not, use instead the following tex ## Code of Conduct Reports The Steering Committee is responsible for handling initial Code of Conduct -reports or incidents. They will receive reports of conduct violations -confidentially. If a report is determined to be a violation, they will -recommend action on it appropriate to the scale, nature, and context of the -violation, from requiring an apology, up to expulsion of an individual from the +reports or incidents. They will receive reports of conduct violations +confidentially. If a report is determined to be a violation, they will +recommend action on it appropriate to the scale, nature, and context of the +violation, from requiring an apology, up to expulsion of an individual from the project. Should any report require a full investigation, or involve a member of the Steering Committee themselves, the report will be forwarded to the CNCF conduct team for handling. @@ -304,7 +304,7 @@ instead. ### Adding and Removing Subprojects -These sections outline the procedure for adding a new subproject, as well as +These sections outline the procedure for adding a new subproject, as well as removing one. There is not a lot of need for customization here, unless you want to specifically spell out additional technical requirements. The one thing you need to spell out is the location of your "archive" or "attic"