mirror of
https://github.com/PowerShell/PowerShell
synced 2026-06-08 12:12:50 +00:00
refactor maintainer and governance docs
Now that we've gotten enough of a sign-off from everyone involved in the governance process, the docs need to be reworked to use a consistent terminology set, links, and directory structure.
This commit is contained in:
joeyaiello
@@ -29,18 +29,18 @@ Quick Start Checklist
|
||||
Contributing to Issues
|
||||
----------------------
|
||||
|
||||
* Review the [Issue Label Descriptions](../docs/dev-process/issue-label-descriptions.md).
|
||||
* Review [Issue Management][issue-management].
|
||||
* Check if the issue you are going to file already exists in our [GitHub issues][open-issue].
|
||||
* If you can't find your issue already,
|
||||
[open a new issue](https://github.com/PowerShell/PowerShell/issues/new),
|
||||
making sure to follow the directions as best you can.
|
||||
* If the issue is marked as [`Help Wanted`][help-wanted-issue],
|
||||
* If the issue is marked as [`help wanted`][help-wanted-issue],
|
||||
the PowerShell maintainers are looking for help with the issue.
|
||||
|
||||
Contributing to Documentation
|
||||
-----------------------------
|
||||
|
||||
### Contributing to documentation related to the PowerShell the product
|
||||
### Contributing to documentation related to PowerShell
|
||||
|
||||
Please see the [Contributor Guide in `PowerShell/PowerShell-Docs`](https://github.com/PowerShell/PowerShell-Docs/blob/staging/CONTRIBUTING.md).
|
||||
|
||||
@@ -86,9 +86,8 @@ Additional references:
|
||||
|
||||
|
||||
|
||||
* If your contribution in a way that changes the user or developer experience,
|
||||
you are expected to document those changes.
|
||||
See [Contributing to documentation related to the PowerShell the product](#contributing-to-documentation-related-to-the-powershell-the-product).
|
||||
* If you're contributing in a way that changes the user or developer experience, you are expected to document those changes.
|
||||
See [Contributing to documentation related to PowerShell](#contributing-to-documentation-related-to-powershell).
|
||||
|
||||
* Add a meaningful title of the PR describing what change you want to check in.
|
||||
Don't simply put: "Fixes issue #5".
|
||||
@@ -251,7 +250,7 @@ Once you sign a CLA, all your existing and future pull requests will be labeled
|
||||
|
||||
[testing-guidelines]: ../docs/testing-guidelines/testing-guidelines.md
|
||||
[running-tests-outside-of-ci]: ../docs/testing-guidelines/testing-guidelines.md#running-tests-outside-of-ci
|
||||
[issue-triage]: ../docs/dev-process/issue-management-process.md
|
||||
[issue-management]: ../docs/maintainers/issue-management.md
|
||||
[governance]: ../docs/community/governance.md
|
||||
[using-prs]: https://help.github.com/articles/using-pull-requests/
|
||||
[fork-a-repo]: https://help.github.com/articles/fork-a-repo/
|
||||
|
||||
@@ -3,13 +3,13 @@
|
||||
## Terms
|
||||
|
||||
* [**PowerShell Committee**](#powershell-committee): A committee of project owners who are responsible for design decisions, approving [RFCs][RFC-repo], and approving new maintainers/committee members
|
||||
* **Project Leads**: Project Leads supports the PowerShell Committee, engineering teams, and community by communicating with other Microsoft teams and leadership as well as other companies to resolve disputes.
|
||||
* **Project Leads**: Project Leads support the PowerShell Committee, engineering teams, and community by working across Microsoft teams and leadership, and working through industry issues with other companies.
|
||||
They also have optional votes on the PowerShell Committee when they choose to invoke them.
|
||||
* [**Repository maintainer**](#repository-maintainers): An individual responsible for merging pull requests (PRs) into `master` when all requirements are met (code review, tests, docs, and RFC approval as applicable).
|
||||
Repository Maintainers are the only people with write permissions into `master`.
|
||||
* [**Area experts**](#area-experts): People who are experts for specific components (e.g. PSReadline, the parser) or technologies (e.g. security, performance).
|
||||
Area experts are responsible for code reviews, issue triage, and providing their expertise to others.
|
||||
* **Corporation**: The Corporation owns the PowerShell repository and, under extreme circumstances, reserves the right to dissolve or reform the PowerShell Committee.
|
||||
* **Corporation**: The Corporation owns the PowerShell repository and, under extreme circumstances, reserves the right to dissolve or reform the PowerShell Committee, the Project Leads, and the Corporate Maintainer.
|
||||
The Corporation for PowerShell is Microsoft.
|
||||
* **Corporate Maintainer**: The Corporate Maintainer is an entity, person or set of persons, with the ability to veto decisions made by the PowerShell Committee or any other collaborators on the PowerShell project.
|
||||
This veto power will be used with restraint since it is intended that the community drive the project.
|
||||
@@ -83,59 +83,9 @@ After the RFC has been discussed, a unanimous vote will be required for the new
|
||||
## Repository Maintainers
|
||||
|
||||
Repository Maintainers are trusted stewards of the PowerShell repository responsible for maintaining consistency and quality of PowerShell code.
|
||||
One of their primary responsibilities is merging pull requests after all requirements have been fulfilled.
|
||||
One of their primary responsibilities is merging pull requests after all requirements have been fulfilled.
|
||||
|
||||
Repository Maintainers have [write access](https://help.github.com/articles/repository-permission-levels-for-an-organization/) to the PowerShell repository which gives them the power to:
|
||||
|
||||
1. Merge pull requests to all branches *including* `master`.
|
||||
1. `git push` to all branches *including* `master`.
|
||||
1. Correctly assigning labels, milestones, and contributors to [issues](https://guides.github.com/features/issues/)
|
||||
|
||||
### Current Repository Maintainers
|
||||
|
||||
* Sergei Vorobev ([vors](https://github.com/vors))
|
||||
* Jason Shirk ([lzybkr](https://github.com/lzybkr))
|
||||
* Dongbo Wang ([daxian-dbw](https://github.com/daxian-dbw))
|
||||
* Travis Plunk ([TravisEz123](https://github.com/TravisEz123))
|
||||
* Mike Richmond ([mirichmo](https://github.com/mirichmo))
|
||||
|
||||
### Repository Maintainer Responsibilities
|
||||
|
||||
Repository Maintainers enable rapid contributions while maintaining a high level of quality in PowerShell by ensuring that all development processes are being followed correctly.
|
||||
|
||||
If you are a Repository Maintainer:
|
||||
|
||||
1. **DO** add [the correct labels](../dev-process/issue-label-descriptions.md) to issues and pull requests
|
||||
1. **DO** make sure that [any change requiring approval from the PowerShell Committee](#changes-that-require-an-rfc) has gone through the proper [RFC][RFC-repo] or approval process
|
||||
1. **DO** make sure the correct [Area Experts](#area-experts) are assigned to relevant pull requests and issues.
|
||||
This includes adding extra reviewers when it makes sense
|
||||
(e.g. a pull request that adds remoting capabilities might require a security expert)
|
||||
1. **DO** validate that code reviews have been performed before merging a pull request
|
||||
1. **DO** validate that applicable tests and documentation have been written before merging a pull request
|
||||
1. **DO** make sure contributors are following the [contributor guidelines](../../.github/CONTRIBUTING.md)
|
||||
1. **DO** ask people to resend a pull request, if it [doesn't target `master`](../../.github/CONTRIBUTING.md#lifecycle-of-a-pull-request).
|
||||
1. **DO** wait for the [CI system][ci-system] build to pass for pull requests.
|
||||
1. **DO** encourage contributors to refer to issues in their pull request description per the [issue template](../../.github/ISSUE_TEMPLATE) (e.g. `Resolves issue #123`)
|
||||
1. **DO** encourage contributors to create meaningful titles for all PRs.
|
||||
Edit the title if necessary to provide clarity on the problem
|
||||
1. **DO** verify that all contributors are following the [Coding Guidlines](../dev-process/coding-guidelines.md)
|
||||
1. **DO** ensure that each contributor has signed a valid Contributor License Agreement (CLA)
|
||||
1. **DO** verify compliance with any third party code license terms (e.g., requiring attribution, etc.) if the contribution contains third party code
|
||||
|
||||
1. **DON'T** merge pull requests with a failed CI build into `master`
|
||||
1. **DON'T** merge pull requests without the label `cla-signed` or `cla-not-required` from the Microsoft CLA bot
|
||||
1. **DON'T** merge pull requests that do not [include all meaningful changes](../../.github/CONTRIBUTING.md#lifecycle-of-a-pull-request) under the **Unreleased** section in the repository's `CHANGELOG.md`
|
||||
1. **DON'T** merge your own pull requests.
|
||||
If a Repository Maintainer opens a pull request, another Maintainer must merge it
|
||||
|
||||
### Becoming a Repository Maintainer
|
||||
|
||||
(TODO: paste from CM) Repository Maintainers currently consist entirely of Microsoft employees, it's expected that trusted, regular contributors to the PowerShell repository will become maintainers themselves.
|
||||
Eligibility is heavily dependent on the level of contribution and expertise: individuals who contribute in meaningful ways to the project will be recognized accordingly.
|
||||
|
||||
At any point in time, a Repository Maintainers can nominate a strong community member to become a Repository Maintainer.
|
||||
Nominations should be submitted in the form of [RFCs][RFC-repo] detailing why that individual is qualified and how they will contribute.
|
||||
After the RFC has been discussed, a unanimous vote by the PowerShell Committee will be required for the new Repository Maintainer to be confirmed.
|
||||
For more information on Repository Maintainers--their responsibilities, who they are, and how one becomes a Maintainer--see the [README for Repository Maintainers][maintainers].
|
||||
|
||||
## Area Experts
|
||||
|
||||
@@ -182,4 +132,5 @@ See our [Pull Request Process][pull-request-process]
|
||||
[breaking-changes]: ../dev-process/breaking-change-contract.md
|
||||
[issue-process]: ../dev-process/issue-label-descriptions.md
|
||||
[pull-request-process]: ../dev-process/pull-request-process.md
|
||||
[docs-contributing]: https://github.com/PowerShell/PowerShell-Docs/blob/staging/CONTRIBUTING.md
|
||||
[docs-contributing]: https://github.com/PowerShell/PowerShell-Docs/blob/staging/CONTRIBUTING.md
|
||||
[maintainers]: ../maintainers/README.md
|
||||
+73
-34
@@ -1,59 +1,86 @@
|
||||
# Repository Maintainers
|
||||
|
||||
Repository maintainers are trusted people with knowledge in the PowerShell domain.
|
||||
Repository Maintainers are trusted stewards of the PowerShell repository responsible for maintaining consistency and quality of PowerShell code.
|
||||
One of their primary responsibilities is merging pull requests after all requirements have been fulfilled.
|
||||
|
||||
They have [write access](https://help.github.com/articles/permission-levels-for-an-organization-repository/) to the PowerShell repositories which gives them the power to:
|
||||
|
||||
1. `push`.
|
||||
2. Merge pull requests.
|
||||
3. Assign labels, milestones, and people to [issues](https://guides.github.com/features/issues/).
|
||||
1. `git push` to the official PowerShell repository
|
||||
2. Merge pull requests
|
||||
3. Assign labels, milestones, and people to [issues](https://guides.github.com/features/issues/)
|
||||
|
||||
## Table of Contents
|
||||
- [Rules](#rules)
|
||||
- [Current Repository Maintainers](#current-repository-maintainers)
|
||||
- [Repository Maintainer Responsibilities](#repository-maintainer-responsibilities)
|
||||
- [Issue Management Process](#issue-management-process)
|
||||
- [Pull Request Workflow](#pull-management-process)
|
||||
- [Abandoned Pull Requests](#abandoned-pull-requests)
|
||||
- [Becoming a Repository Maintainer](#becoming-a-repository-maintainer)
|
||||
|
||||
## Rules
|
||||
## Current Repository Maintainers
|
||||
|
||||
If you are a maintainer, please follow these rules:
|
||||
* Sergei Vorobev ([vors](https://github.com/vors))
|
||||
* Jason Shirk ([lzybkr](https://github.com/lzybkr))
|
||||
* Dongbo Wang ([daxian-dbw](https://github.com/daxian-dbw))
|
||||
* Travis Plunk ([TravisEz123](https://github.com/TravisEz123))
|
||||
* Mike Richmond ([mirichmo](https://github.com/mirichmo))
|
||||
* Andy Schwartzmeyer ([andschwa](https://github.com/andschwa))
|
||||
|
||||
1. **DO** reply to new issues and pull requests (while reviewing PRs, leave your comment even if everything looks good - simple "Looks good to me" or "LGTM" will suffice, so that we know someone has already taken a look at it).
|
||||
1. **DO** make sure contributors are following the [contributor guidelines](../../.github/CONTRIBUTING.md).
|
||||
1. **DO** ask people to resend a pull request, if it targets [the wrong branch](../../.github/CONTRIBUTING.md#lifecycle-of-a-pull-request).
|
||||
1. **DO** encourage people to write Pester tests for all new/changed functionality.
|
||||
1. **DO** wait for the [CI system][ci-system] build to pass for pull requests.
|
||||
1. **DO** encourage contributors to refer to issues in PR title/description (e.g. ```Closes #11```). Edit title if necessary.
|
||||
1. **DO** encourage contributors to create meaningful titles for all PRs. Edit title if necessary.
|
||||
1. **DO** verify that all contributors are following the [coding guidelines](../dev-process/coding-guidelines.md).
|
||||
1. **DO** ensure that each contributor has signed a valid Contributor License Agreement (CLA).
|
||||
1. **DO** verify compliance with any third party code license terms (e.g., requiring attribution, etc.) if the contribution contains third party code.
|
||||
## Repository Maintainer Responsibilities
|
||||
|
||||
1. **DON'T** merge pull requests with a failed CI build.
|
||||
1. **DON'T** merge pull requests without the label `cla-signed` or `cla-not-required` from the Microsoft CLA bot.
|
||||
1. **DON'T** merge pull requests that do not [include all meaningful changes](../../.github/CONTRIBUTING.md#lifecycle-of-a-pull-request) under the **Unreleased** section in the repository's `CHANGELOG.md`.
|
||||
1. **DON'T** merge your own pull requests before they are reviewed by someone else.
|
||||
- If there is **no one** else to review your pull request, please wait **24** hours to merge it in case anyone comes along and has a comment.
|
||||
Repository Maintainers enable rapid contributions while maintaining a high level of quality in PowerShell by ensuring that all development processes are being followed correctly.
|
||||
|
||||
If you are a Repository Maintainer, you:
|
||||
|
||||
1. **MUST** ensure that each contributor has signed a valid Contributor License Agreement (CLA)
|
||||
1. **MUST** verify compliance with any third party code license terms (e.g., requiring attribution, etc.) if the contribution contains third party code.
|
||||
1. **MUST** make sure that [any change requiring approval from the PowerShell Committee](#changes-that-require-an-rfc) has gone through the proper [RFC][RFC-repo] or approval process
|
||||
1. **MUST** validate that code reviews have been conducted before merging a pull request when no code is written
|
||||
1. **MUST** validate that tests and documentation have been written before merging a pull request that contains new functionality
|
||||
1. **SHOULD** add [the correct labels][issue-management] to issues and pull requests
|
||||
1. **SHOULD** make sure the correct [Area Experts](#area-experts) are assigned to relevant pull requests and issues.
|
||||
This includes adding extra reviewers when it makes sense
|
||||
(e.g. a pull request that adds remoting capabilities might require a security expert)
|
||||
1. **SHOULD** validate that the names and email addresses in the git commits reasonably match identity of the person submitting the pull request
|
||||
1. **SHOULD** make sure contributors are following the [contributor guidelines][CONTRIBUTING]
|
||||
1. **SHOULD** ask people to resend a pull request, if it [doesn't target `master`](../../.github/CONTRIBUTING.md#lifecycle-of-a-pull-request)
|
||||
1. **SHOULD** wait for the [CI system][ci-system] build to pass for pull requests
|
||||
(unless, for instance, the pull request is being submitted to fix broken CI)
|
||||
1. **SHOULD** encourage contributors to refer to issues in their pull request description per the [issue template](../../.github/ISSUE_TEMPLATE) (e.g. `Resolves issue #123`)
|
||||
1. **SHOULD** encourage contributors to create meaningful titles for all PRs.
|
||||
Edit the title if necessary to provide clarity on the problem
|
||||
1. **SHOULD** encourage contributes to write meaningful, descriptive git commits
|
||||
1. **SHOULD NOT** merge pull requests with a failed CI build
|
||||
(unless, for instance, the pull request is being submitted to fix broken CI)
|
||||
1. **SHOULD NOT** merge pull requests without the label `cla-signed` or `cla-not-required` from the Microsoft CLA bot
|
||||
(unless the CLA bot is broken, and CLA signing can be confirmed through other means)
|
||||
1. **SHOULD NOT** merge pull requests too quickly after they're submitted.
|
||||
Even if the pull request meets all the requirements, people should have time to give their input
|
||||
(unless the pull request is particularly urgent for some reason)
|
||||
1. **SHOULD NOT** merge your own pull requests.
|
||||
If a Repository Maintainer opens a pull request, another Maintainer should merge it unless there are extreme, short-term circumstances requiring a merge or another Maintainer has given explicit sign-off without merging
|
||||
|
||||
## Issue Management Process
|
||||
|
||||
Please see [Issue Management Process](./issue-management-process.md)
|
||||
Please see [Issue Management][issue-management]
|
||||
|
||||
## Pull Request Workflow
|
||||
|
||||
1. A contributor opens a pull request.
|
||||
2. The contributor ensures that their pull request passes the [CI system][ci-system] build.
|
||||
1. The contributor ensures that their pull request passes the [CI system][ci-system] build.
|
||||
- If the build fails, a maintainer adds the ```waiting for author``` label to the pull request.
|
||||
The contributor can then continue to update the pull request until the build passes.
|
||||
2. Once the build passes, the maintainer either reviews the pull request immediately or adds the ```need review``` label.
|
||||
3. A maintainer or trusted contributor reviews the pull request code.
|
||||
The contributor can then continue to update the pull request until the build passes.
|
||||
1. Once the build passes, the maintainer either reviews the pull request immediately or adds the ```need review``` label.
|
||||
1. A maintainer or trusted contributor reviews the pull request code.
|
||||
- If the contributor does not meet the reviewer's standards, the reviewer makes comments.
|
||||
A maintainer then removes the ```need review``` label and adds the ```waiting for author``` label.
|
||||
The contributor must address the comments and repeat from step 2.
|
||||
A maintainer then removes the ```need review``` label and adds the ```waiting for author``` label.
|
||||
The contributor must address the comments and repeat from step 2.
|
||||
- If the contributor meets the reviewer's standards, the reviewer comments that they are satisfied.
|
||||
A maintainer then removes the ```need review``` label.
|
||||
3. Once the code review is completed, a maintainer merges the pull request.
|
||||
A maintainer then removes the ```need review``` label.
|
||||
1. Once the code review is completed, a maintainer merges the pull request.
|
||||
|
||||
### Abandoned Pull Requests
|
||||
|
||||
A pull request with the label ```waiting for the author``` for **more than two weeks** without a word from the author is considered abandoned.
|
||||
|
||||
In these cases:
|
||||
@@ -61,9 +88,21 @@ In these cases:
|
||||
1. Ping the author of PR to remind him of pending changes.
|
||||
- If the contributor responds, it's no longer an abandoned pull request, proceed as normal.
|
||||
2. If the contributor does not respond **within a week**:
|
||||
- If the reviewer's comments are very minor, merge the change, fix the code immediately, and create a new PR with the fixes addressing the minor comments.
|
||||
- If the changes required to merge the pull request are significant but needed, create a new branch with the changes and open an issue to merge the code into the dev branch.
|
||||
Mention the original pull request ID in the description of the new issue and close the abandoned pull request.
|
||||
- Create a new branch with the changes and open an issue to merge the code into the dev branch.
|
||||
Mention the original pull request ID in the description of the new issue and close the abandoned pull request.
|
||||
- If the changes in an abandoned pull request are no longer needed (e.g. due to refactoring of the code base or a design change), simply close the pull request.
|
||||
|
||||
## Becoming a Repository Maintainer
|
||||
|
||||
Repository Maintainers currently consist entirely of Microsoft employees
|
||||
It is expected that over time, regular trusted contributors to the PowerShell repository will be made Repository Maintainers.
|
||||
Eligibility is heavily dependent on the level of contribution and expertise: individuals who contribute in meaningful ways to the project will be recognized accordingly.
|
||||
|
||||
At any point in time, a Repository Maintainers can nominate a strong community member to become a Repository Maintainer.
|
||||
Nominations should be submitted in the form of [RFCs][RFC-repo] detailing why that individual is qualified and how they will contribute.
|
||||
After the RFC has been discussed, a unanimous vote by the PowerShell Committee will be required for the new Repository Maintainer to be confirmed.
|
||||
|
||||
[RFC-repo]: https://github.com/PowerShell/PowerShell-RFC
|
||||
[ci-system]: ../testing-guidelines/testing-guidelines.md#ci-system
|
||||
[issue-management]: issue-management.md
|
||||
[CONTRIBUTING]: ../../.github/CONTRIBUTING.MD
|
||||
@@ -1,12 +0,0 @@
|
||||
author: Jason/Andy
|
||||
|
||||
|
||||
> meaning of label, assignees, etc.
|
||||
> triage process
|
||||
> requirements for resolving (timing), closing...
|
||||
|
||||
# Maintainer - Issue Management Process
|
||||
|
||||
## Issue Label Descriptions
|
||||
|
||||
See [Issue Label Descriptions](../dev-process/issue-label-descriptions)
|
||||
@@ -1,3 +1,5 @@
|
||||
# Issue Management
|
||||
|
||||
## Long-living issue labels
|
||||
|
||||
### Feature areas
|
||||
@@ -38,5 +40,7 @@ Issues can be in one of the following states:
|
||||
The assignee(s) are responsible for signing off before the PR will be merged.
|
||||
|
||||
* `help wanted` : We are looking for someone to work on this issue.
|
||||
* `need review` : This Pull Request is being reviewed. Please see [Pull Request - Code Review](../../.github/CONTRIBUTING.md#pull-request-code-review)
|
||||
* `need review` : This pull request is being reviewed. Please see [Pull Request - Code Review](../../.github/CONTRIBUTING.md#pull-request-code-review)
|
||||
* `waiting for author`: The issue or pull request needs
|
||||
* `add to changelog`: The PR requires an addition to the changelog.
|
||||
Should be removed when it has been added.
|
||||
@@ -1,15 +1,5 @@
|
||||
# Pull Request Process
|
||||
|
||||
author: Hemant
|
||||
> Hemant: "SLAs" for pull requests
|
||||
> ALWAYS point to documents when critiquing PRs
|
||||
> this should also include the blackbox of Windows/STEX testing
|
||||
> "some tests we can only run internally"
|
||||
> exact timeline not need for Aug17
|
||||
> Windows quality gates
|
||||
|
||||
## Minimum gates (TODO)
|
||||
|
||||
Our [pull request template][pr-template] includes the bare minimum requirements for a pull request to be accepted into PowerShell. This includes:
|
||||
* Writing tests
|
||||
* Writing documentation (where does thie one live already? is it where this guidance should exist all up?)
|
||||
@@ -1,18 +0,0 @@
|
||||
author: Hemant
|
||||
> Hemant: "SLAs" for pull requests
|
||||
> ALWAYS point to documents when critiquing PRs
|
||||
> this should also include the blackbox of Windows/STEX testing
|
||||
> time can totally be wishy-washy here
|
||||
> "some tests we can only run internally"
|
||||
> exact timeline not need for Aug17
|
||||
> Windows quality gates
|
||||
|
||||
## Minimum gates (TODO)
|
||||
|
||||
Our [pull request template][pr-template] includes the bare minimum requirements for a pull request to be accepted into PowerShell. This includes:
|
||||
* Writing tests
|
||||
* Writing documentation (where does thie one live already? is it where this guidance should exist all up?)
|
||||
* Repository maintainer sign-off, per our [governance model][governance]
|
||||
|
||||
[pr-template]: ../../.github/PULL_REQUEST_TEMPLATE.md
|
||||
[governance]: ../community/governance.md
|
||||
Reference in New Issue
Block a user