[WIP] review of project governance #1540

joeyaiello · 2016-07-27T17:45:40Z

Please don't merge this PR yet

Resolves the need for an all-up governance doc.
Code is up-to-date with master.
[N/A] Add tests that fail without your changes.
Update all relevant documentation.

This is purely a WIP review to make sure I'm not completely out of left field here. I still need to do a considerable rewrite of the other contributor docs in order to change terminology to align with this document (e.g. maintainers.md, contributing.md, etc.)

EDIT: Thanks to @TravisEz13 and @KarolKaczmarek for giving me some existing documentation, governance, and structure to work with. :)

TravisEz13 · 2016-07-27T18:24:14Z

README.md

+If you are new to Git, we recommend you start by reviewing our
+[Git basics document][git-basics] where you will find Git installation
+instructions, cheat sheets and links to our favorite Git tutorials. We also
+recommend, reviewing an example of a [basic Git commit walkthrough][git-commit]. 


This section is duplicated but different than what is in contributing.md. Perhaps this should be a sub-section and contributing should link back here or the other way around.

joeyaiello · 2016-07-27T18:48:57Z

Didn't meant to include a bunch of those edits in my weak attempt at a rebase. My apologies. I'm inline with master now #Resolved

TravisEz13 · 2016-07-27T21:55:19Z

docs/community/governance.md

+
+### PowerShell Committee Membership
+


The entire time I was reading I was wondering where this section was. #Resolved

So you think it should be moved up? Actually received feedback to move it down, but I'm open to more suggestion. #Resolved

yeah, because basically I don't know what you are talking about the whole time.

In reply to: 72535762 [](ancestors = 72535762)

Done #Resolved

TravisEz13 · 2016-07-27T22:19:54Z

🕐

TravisEz13 · 2016-07-28T21:36:31Z

1 comments do not have a response. #Pending

TravisEz13 · 2016-08-07T16:33:27Z

docs/community/governance.md

+1. **DO** ensure that contributors [write Pester tests][pester] for all new/changed functionality
+1. **DO** ensure that contributors [write documentation][docs-contributing] for all new-/changed functionality
+1. **DO** encourage contributors to refer to issues in their pull request description per the [issue template](../../.github/ISSUE_TEMPLATE.md) (e.g. `Resolves issue #123`)


This should be per the pull request template

TravisEz13 · 2016-08-09T03:02:54Z

See [this][closing-via-message] for more details.

This does not agree with the maintainers readme.md
`SHOULD encourage contributors to refer to issues in their pull request description ...'

Either this should say that they should open a new issues if one does not exist, or the maintainers readme should be qualified, with if the issue already exists #Pending

Refers to: .github/CONTRIBUTING.md:101 in ee5a755. [](commit_id = ee5a755540086ff5475a6b67a1330f16b49a83c0, deletion_comment = False)

TravisEz13 · 2016-08-09T03:03:40Z

Otherwise, these issues should be treated like any other issue in this repo.

There have been comments that doc issues should not require opening an issue. Example #Pending

Refers to: .github/CONTRIBUTING.md:51 in ee5a755. [](commit_id = ee5a755540086ff5475a6b67a1330f16b49a83c0, deletion_comment = False)

joeyaiello · 2016-08-09T22:50:58Z

Had an offline conversation with @TravisEz13 about issues being created prior to pull requests. I'm making some final modifications to this PR that should communicate the following:

issues should be created prior to doing large pieces of work. This is to try and minimize the duplication of effort on significant bodies of work
a PR should not be blocked on whether an issue exists. If they've done the work, and the work is sound, and the PR meets all the bars to being accepted by a repository maintainer, it should be accepted. Any discussion on it can happen in the PR.
however, that PR submitter should be reminded that, next time, they should start an issue to get this discussion and approval out of the way BEFORE they do a bunch of work. This is to minimize duplication of efforts and to minimize having to redo work that didn't get discussed or approved

Sound okay? #Resolved

joeyaiello · 2016-08-09T22:51:15Z

Also, we need to merge this guy. We can continue to make any minor fixes over the next couple days, but it's gotta go in.

still need to do a considerable rewrite of other contributor docs in order to change terminology to align with governance.md

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.

joeyaiello · 2016-08-09T23:45:50Z

Alright, @TravisEz13, everything should be merged up here. Can I get a signoff and merge from you? Thanks! #Pending

alexandair · 2016-08-09T23:54:54Z

That section about issues prior to PR applies to code-related PR? Or, docs-related PRs too?

joeyaiello · 2016-08-10T16:29:29Z

@alexandair the spirit of the guideline is, again, to minimize duplication of efforts and churn in one place. It's a poor-man's work tracking mechanism.

But given the spirit of the rule, you don't need to go file an issue for every typo. However, I do think there's some benefit to saying "hey, semantic line feeds are busted all over the repo, I'm going to go tackle that" and just giving people a heads up before changing 15-20 files. And there's certainly benefit to saying "hey, I'm going to go move a bunch of files around" or "I'm going to go refactor these sets of docs and move headers and content between files/folders". I say this from personal experience: this PR was super hard to get merged because of how much a moving target master was. (And not just the technical aspects of rebasing, but conceptually keeping track of often undiscussed decisions people were codifying throughout the maintainer and contributor documentation.)

I know it feels like needless process now, but I'd rather err on the side of a little process before we open the floodgates.

Plus, I also don't expect contributor documentation here to be changing significantly after the first month we're live. So, to be honest, I think it's kind of a no-op.

TravisEz13 · 2016-08-10T18:53:23Z

docs/maintainers/README.md

+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`).


he [issue template](. [](start = 95, length = 21)

Should be PR template

TravisEz13 · 2016-08-10T18:56:19Z

This looks good to me other than, this comment: #1540 (diff)

We should merge and file an issue for this.

joeyaiello · 2016-08-11T20:48:34Z

Looks like I forgot to do it in both places. Should be fixed now

joeyaiello added the need review label Jul 27, 2016

TravisEz13 reviewed Jul 27, 2016
View reviewed changes

joeyaiello force-pushed the joey/governance branch 2 times, most recently from 3c93421 to d059425 Compare July 27, 2016 18:48

joeyaiello force-pushed the joey/governance branch from d059425 to 748ee6b Compare July 27, 2016 18:49

TravisEz13 reviewed Jul 27, 2016
View reviewed changes

joeyaiello force-pushed the joey/governance branch 3 times, most recently from 7a7f948 to 6f5737d Compare August 4, 2016 20:38

daxian-dbw removed the Review - needed label Aug 5, 2016

TravisEz13 reviewed Aug 7, 2016
View reviewed changes

TravisEz13 mentioned this pull request Aug 9, 2016

Update docs/FAQ.md #1640

Merged

4 tasks

joeyaiello added 5 commits August 9, 2016 16:42

first pass of governance doc

c15eb54

still need to do a considerable rewrite of other contributor docs in order to change terminology to align with governance.md

respond to PR feedback on governance

040c980

address offline feedback for governance

d9b1093

refactor maintainer and governance docs

42019e5

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.

fix broken links in governance PR

c9ae0c3

joeyaiello force-pushed the joey/governance branch from 468812e to ee5a755 Compare August 9, 2016 23:45

joeyaiello added Review - needed and removed Review - waiting on author labels Aug 9, 2016

TravisEz13 added the Area-Maintainers-Documentation specific to documentation in this repo label Aug 10, 2016

TravisEz13 reviewed Aug 10, 2016
View reviewed changes

TravisEz13 added this to the 6.0.0-Alpha.9 milestone Aug 10, 2016

TravisEz13 self-assigned this Aug 10, 2016

TravisEz13 mentioned this pull request Aug 10, 2016

Maintainers Readme refers to wrong template for PRs #1710

Closed

address final PR/offline feedback for governance

580c7b7

joeyaiello force-pushed the joey/governance branch from ee5a755 to 580c7b7 Compare August 11, 2016 20:48

TravisEz13 merged commit cf23084 into master Aug 11, 2016

PowerShellTeam removed the Review - needed label Aug 11, 2016

TravisEz13 deleted the joey/governance branch August 11, 2016 21:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] review of project governance #1540

[WIP] review of project governance #1540

joeyaiello commented Jul 27, 2016 •

edited

TravisEz13 Jul 27, 2016

joeyaiello commented Jul 27, 2016 •

edited by TravisEz13

TravisEz13 Jul 27, 2016 •

edited

joeyaiello Jul 27, 2016 •

edited by TravisEz13

TravisEz13 Jul 28, 2016

joeyaiello Jul 28, 2016 •

edited by TravisEz13

TravisEz13 commented Jul 27, 2016

TravisEz13 commented Jul 28, 2016 •

edited

TravisEz13 Aug 7, 2016

TravisEz13 commented Aug 9, 2016 •

edited

TravisEz13 commented Aug 9, 2016 •

edited

joeyaiello commented Aug 9, 2016 •

edited by TravisEz13

joeyaiello commented Aug 9, 2016

joeyaiello commented Aug 9, 2016 •

edited by TravisEz13

alexandair commented Aug 9, 2016

joeyaiello commented Aug 10, 2016

TravisEz13 Aug 10, 2016

TravisEz13 commented Aug 10, 2016

joeyaiello commented Aug 11, 2016

[WIP] review of project governance #1540

[WIP] review of project governance #1540

Conversation

joeyaiello commented Jul 27, 2016 • edited

TravisEz13 Jul 27, 2016

Choose a reason for hiding this comment

joeyaiello commented Jul 27, 2016 • edited by TravisEz13

TravisEz13 Jul 27, 2016 • edited

Choose a reason for hiding this comment

joeyaiello Jul 27, 2016 • edited by TravisEz13

Choose a reason for hiding this comment

TravisEz13 Jul 28, 2016

Choose a reason for hiding this comment

joeyaiello Jul 28, 2016 • edited by TravisEz13

Choose a reason for hiding this comment

TravisEz13 commented Jul 27, 2016

TravisEz13 commented Jul 28, 2016 • edited

TravisEz13 Aug 7, 2016

Choose a reason for hiding this comment

TravisEz13 commented Aug 9, 2016 • edited

TravisEz13 commented Aug 9, 2016 • edited

joeyaiello commented Aug 9, 2016 • edited by TravisEz13

joeyaiello commented Aug 9, 2016

joeyaiello commented Aug 9, 2016 • edited by TravisEz13

alexandair commented Aug 9, 2016

joeyaiello commented Aug 10, 2016

TravisEz13 Aug 10, 2016

Choose a reason for hiding this comment

TravisEz13 commented Aug 10, 2016

joeyaiello commented Aug 11, 2016

joeyaiello commented Jul 27, 2016 •

edited

joeyaiello commented Jul 27, 2016 •

edited by TravisEz13

TravisEz13 Jul 27, 2016 •

edited

joeyaiello Jul 27, 2016 •

edited by TravisEz13

joeyaiello Jul 28, 2016 •

edited by TravisEz13

TravisEz13 commented Jul 28, 2016 •

edited

TravisEz13 commented Aug 9, 2016 •

edited

TravisEz13 commented Aug 9, 2016 •

edited

joeyaiello commented Aug 9, 2016 •

edited by TravisEz13

joeyaiello commented Aug 9, 2016 •

edited by TravisEz13