From c55af05066bf1ace210b972bbee813012ed92cc4 Mon Sep 17 00:00:00 2001 From: sam boyer Date: Mon, 5 Jun 2017 21:42:16 -0400 Subject: [PATCH 1/5] Add first draft of maintainer's guide --- CONTRIBUTING.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09a4bacaa4..c00d4f753f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to Dep -Dep is an open source project. +`dep` is an open source project. It is the work of hundreds of contributors. We appreciate your help! @@ -52,3 +52,43 @@ your current agreements on file or to sign a new one. You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again. + +## Maintainer's Guide + +`dep` has subsystem maintainers; this guide is intended for them in performing their work as a maintainer. + +### General guidelines + +* _Be kind, respectful, and inclusive_. Really live [that CoC](https://github.com/golang/dep/blob/master/CODE_OF_CONDUCT.md). We've developed a reputation as one of the most welcoming and supportive project environments in the Go community, and we want to keep that up! +* The lines of responsibility between maintainership areas can be fuzzy. Get to know your fellow maintainers - it's important to work _with_ them when an issue falls in this grey area. +* Remember, the long-term goal of `dep` is to disappear into the `go` toolchain. That's going to be a challenging process, no matter what. Minimizing that eventual difficulty should be a guiding light for all your decisions today. +* Being a maintainer doesn't mean you're always right. Admitting when you've made a mistake keeps the code flowing, the environment health, and the respect level up. +* It's fine if you need to step back from maintainership responsibilities - just, please, don't fade away! Let other maintainers know what's going on. + +### Issue management + +* We use [Zenhub](https://www.zenhub.com) to manage the queue, in addition to what we do with labels. + * Pipelines, and [the board](https://github.com/golang/dep#boards) are one thing we try to utilize + * Marking dependencies/blockers is also quite useful where appropriate; please do that. + * We use epics and milestones in roughly the same way (because OSS projects don't have real sprints). Epics should be duplicated as milestones; if there's a main epic issue, it should contain a checklist of the relevant issues to complete it. +* The `area:` labels correspond to maintainership areas. Apply yours to any issues or PRs that fall under your purview. It's to be expected that multiple `area:` labels may be applied to a single issue. +* The [`help-wanted`](https://github.com/golang/dep/issues?q=is%3Aissue+is%3Aopen+label%3Ahelp-wanted) and [`good-first-pr`](https://github.com/golang/dep/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-pr) labels are two of our most important tools for making the project accessible to newcomers - a key goal for our community. Here's how to use them well. + * `good-first-pr` should be applied when there's a very straightforward, self-contained task that is very unlikely to have any hidden complexity. The real purpose of these is to provide a "chink in the armor", providing newcomers a lens through which to start understanding the project. + * `help-wanted` should be applied to issues where there's a clear, stated goal, there is at most one significant question that needs answering, and it looks like the implementation won't be inordinately difficult, or disruptive to other parts of the system. + * `help-wanted` should also be applied to all `good-first-pr` issues - it's duplicative, but not doing so seems unfriendly. + + +### Pull Requests + +* Try to encourage, and make, smaller pull requests. +* [No is temporary. Yes is forever](https://blog.jessfraz.com/post/the-art-of-closing/). +* Long-running feature branches should generally be avoided. Discuss it with other maintainers first. +* Unless it's trivial, don't merge your own PRs - ask another maintainer. +* Commits should follow [Tim Pope's rules](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +* Merge checklist! + * Does the PR pass [the code review comments](https://github.com/golang/go/wiki/CodeReviewComments)? (internalize these rules!) + * Are there tests to cover new or changed behavior? Prefer reliable tests > no tests > flaky tests. + * Does the first post in the PR contain "Fixes #..." text for any issues it resolves? + * Are any necessary follow-up issues _already_ posted, prior to merging? + * Does this change entail the updating of any docs? + * For docs kept in the repo, e.g. FAQ.md, docs changes _must_ be submitted as part of the same PR. \ No newline at end of file From 0fd5e0af8fd1bf751a9a64546c61dadbfae773d5 Mon Sep 17 00:00:00 2001 From: sam boyer Date: Mon, 5 Jun 2017 22:12:31 -0400 Subject: [PATCH 2/5] Add issue and PR templates --- .github/ISSUE_TEMPLATE.md | 23 +++++++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 12 ++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000000..5ac1c6bfb9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,23 @@ + + +### What version of Go (`go version`) and `dep` are you using? + +### What `dep` command did you run? + + + +### What did you expect to see? + +### What did you see instead? + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..adcafdcce8 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,12 @@ +### What does this do / why do we need it? + +### What should your reviewer look out for in this PR? + +### Which issue(s) does this PR fix? + +<-- + +fixes # +fixes # + +--> From bac56b4d62a774ff8150f7c00bcf2d4124721515 Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Mon, 5 Jun 2017 23:11:20 -0500 Subject: [PATCH 3/5] Explain our zenhub pipelines --- CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c00d4f753f..8fa4576283 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,6 +69,9 @@ again. * We use [Zenhub](https://www.zenhub.com) to manage the queue, in addition to what we do with labels. * Pipelines, and [the board](https://github.com/golang/dep#boards) are one thing we try to utilize + * **New Issues Pipeline**: When someone creates a new issue, it goes here first. Keep an eye out for issues that fall into your area. Add labels to them, and if it's something we should do, put it in the `Backlog` pipeline. If you aren't sure, throw it in the `Icebox`. It helps to sort this pipeline by date. + * **Icebox Pipeline**: Issues that we aren't immediately closing but aren't really ready to be prioritized and started on. It's not a wontfix bucket, but a "not sure if we should/can fix right now" bucket. + * **Backlog Pipeline**: Issues that we know we want to tackle. You can drag/drop up and down to prioritize issues. * Marking dependencies/blockers is also quite useful where appropriate; please do that. * We use epics and milestones in roughly the same way (because OSS projects don't have real sprints). Epics should be duplicated as milestones; if there's a main epic issue, it should contain a checklist of the relevant issues to complete it. * The `area:` labels correspond to maintainership areas. Apply yours to any issues or PRs that fall under your purview. It's to be expected that multiple `area:` labels may be applied to a single issue. @@ -91,4 +94,4 @@ again. * Does the first post in the PR contain "Fixes #..." text for any issues it resolves? * Are any necessary follow-up issues _already_ posted, prior to merging? * Does this change entail the updating of any docs? - * For docs kept in the repo, e.g. FAQ.md, docs changes _must_ be submitted as part of the same PR. \ No newline at end of file + * For docs kept in the repo, e.g. FAQ.md, docs changes _must_ be submitted as part of the same PR. From 587698abe8cd5f5266b9cd69808dbad8b5ce5c4a Mon Sep 17 00:00:00 2001 From: sam boyer Date: Tue, 6 Jun 2017 12:04:17 -0400 Subject: [PATCH 4/5] Update with review comments --- .github/ISSUE_TEMPLATE.md | 4 ++-- .github/PULL_REQUEST_TEMPLATE.md | 9 ++++++++- CONTRIBUTING.md | 33 ++++++++++++++++---------------- 3 files changed, 26 insertions(+), 20 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 5ac1c6bfb9..7a3ef43a0f 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -5,7 +5,7 @@ everthing here and write out the request, providing as much context as you can. --> -### What version of Go (`go version`) and `dep` are you using? +### What version of Go (`go version`) and `dep` (`git describe --tags`) are you using? ### What `dep` command did you run? @@ -13,7 +13,7 @@ everthing here and write out the request, providing as much context as you can. Paste the output of the commands you ran in here, making sure to pass -v for maximum context. -Including the ouptut of `dep hash-inputs` may also be helpful to include here. +The output of `dep hash-inputs` may also be helpful to include. --> diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index adcafdcce8..b77e62c15c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,8 +1,15 @@ +<-- +Work-in-progress PRs are welcome as a way to get early feedback - just prefix +the title with [WIP]. +--> + ### What does this do / why do we need it? ### What should your reviewer look out for in this PR? -### Which issue(s) does this PR fix? +### Do you need help or clarification on anything? + +### Which issue(s) does this PR fix? <-- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8fa4576283..ec7f78772f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to Dep +# Contributing to `dep` `dep` is an open source project. @@ -12,9 +12,8 @@ Please check the existing issues and [FAQ](FAQ.md) to see if your feedback has a When [filing an issue](https://github.com/golang/dep/issues/new), make sure to answer these five questions: -1. What version of Go are you using (`go version`)? -2. What operating system and processor architecture are you using? -3. What did you do? +1. What version of Go (`go version`) and `dep` (`git describe --tags`) are you using?? +3. What `dep` command did you run? 4. What did you expect to see? 5. What did you see instead? @@ -32,7 +31,7 @@ label highlights issues that are well-suited for folks to jump in on. The [good-first-pr](https://github.com/golang/dep/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-pr) label further identifies issues that are particularly well-sized for newcomers. -Unless otherwise noted, the Dep source files are distributed under +Unless otherwise noted, the `dep` source files are distributed under the BSD-style license found in the LICENSE file. All submissions, including submissions by project members, require review. We @@ -68,7 +67,7 @@ again. ### Issue management * We use [Zenhub](https://www.zenhub.com) to manage the queue, in addition to what we do with labels. - * Pipelines, and [the board](https://github.com/golang/dep#boards) are one thing we try to utilize + * Pipelines, and [the board](https://github.com/golang/dep#boards) are one thing we try to utilize: * **New Issues Pipeline**: When someone creates a new issue, it goes here first. Keep an eye out for issues that fall into your area. Add labels to them, and if it's something we should do, put it in the `Backlog` pipeline. If you aren't sure, throw it in the `Icebox`. It helps to sort this pipeline by date. * **Icebox Pipeline**: Issues that we aren't immediately closing but aren't really ready to be prioritized and started on. It's not a wontfix bucket, but a "not sure if we should/can fix right now" bucket. * **Backlog Pipeline**: Issues that we know we want to tackle. You can drag/drop up and down to prioritize issues. @@ -78,20 +77,20 @@ again. * The [`help-wanted`](https://github.com/golang/dep/issues?q=is%3Aissue+is%3Aopen+label%3Ahelp-wanted) and [`good-first-pr`](https://github.com/golang/dep/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-pr) labels are two of our most important tools for making the project accessible to newcomers - a key goal for our community. Here's how to use them well. * `good-first-pr` should be applied when there's a very straightforward, self-contained task that is very unlikely to have any hidden complexity. The real purpose of these is to provide a "chink in the armor", providing newcomers a lens through which to start understanding the project. * `help-wanted` should be applied to issues where there's a clear, stated goal, there is at most one significant question that needs answering, and it looks like the implementation won't be inordinately difficult, or disruptive to other parts of the system. - * `help-wanted` should also be applied to all `good-first-pr` issues - it's duplicative, but not doing so seems unfriendly. + * `help-wanted` should also be applied to all `good-first-pr` issues - it's duplicative, but not doing so seems unfriendly. ### Pull Requests -* Try to encourage, and make, smaller pull requests. -* [No is temporary. Yes is forever](https://blog.jessfraz.com/post/the-art-of-closing/). +* Try to make, and encourage, smaller pull requests. +* [No is temporary. Yes is forever.](https://blog.jessfraz.com/post/the-art-of-closing/) * Long-running feature branches should generally be avoided. Discuss it with other maintainers first. * Unless it's trivial, don't merge your own PRs - ask another maintainer. -* Commits should follow [Tim Pope's rules](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). -* Merge checklist! - * Does the PR pass [the code review comments](https://github.com/golang/go/wiki/CodeReviewComments)? (internalize these rules!) - * Are there tests to cover new or changed behavior? Prefer reliable tests > no tests > flaky tests. - * Does the first post in the PR contain "Fixes #..." text for any issues it resolves? - * Are any necessary follow-up issues _already_ posted, prior to merging? - * Does this change entail the updating of any docs? - * For docs kept in the repo, e.g. FAQ.md, docs changes _must_ be submitted as part of the same PR. +* Commit messages should follow [Tim Pope's rules](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +* Checklist for merging PRs: + * Does the PR pass [the code review comments](https://github.com/golang/go/wiki/CodeReviewComments)? (internalize these rules!) + * Are there tests to cover new or changed behavior? Prefer reliable tests > no tests > flaky tests. + * Does the first post in the PR contain "Fixes #..." text for any issues it resolves? + * Are any necessary follow-up issues _already_ posted, prior to merging? + * Does this change entail the updating of any docs? + * For docs kept in the repo, e.g. FAQ.md, docs changes _must_ be submitted as part of the same PR. From e4246bd43c8b599bd339427c6898266a92db1a9f Mon Sep 17 00:00:00 2001 From: sam boyer Date: Tue, 6 Jun 2017 12:26:15 -0400 Subject: [PATCH 5/5] Clarify aligning with toolchain a bit more --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ec7f78772f..3717fca9db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,6 +61,9 @@ again. * _Be kind, respectful, and inclusive_. Really live [that CoC](https://github.com/golang/dep/blob/master/CODE_OF_CONDUCT.md). We've developed a reputation as one of the most welcoming and supportive project environments in the Go community, and we want to keep that up! * The lines of responsibility between maintainership areas can be fuzzy. Get to know your fellow maintainers - it's important to work _with_ them when an issue falls in this grey area. * Remember, the long-term goal of `dep` is to disappear into the `go` toolchain. That's going to be a challenging process, no matter what. Minimizing that eventual difficulty should be a guiding light for all your decisions today. + * Try to match the toolchain's assumptions as closely as possible ([example](https://github.com/golang/dep/issues/564#issuecomment-300994599)), and avoid introducing new rules the toolchain would later have to incorporate. + * Every new flag or option in the metadata files is more exposed surface area that demands conversion later. Only add these with a clear design plan. + * `dep` is experimental, but increasingly only on a larger scale. Experiments need clear hypotheses and parameters for testing - nothing off-the-cuff. * Being a maintainer doesn't mean you're always right. Admitting when you've made a mistake keeps the code flowing, the environment health, and the respect level up. * It's fine if you need to step back from maintainership responsibilities - just, please, don't fade away! Let other maintainers know what's going on.