From 12f0371647b253dd7fc0b57a76edb1dc456b57c8 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Fri, 19 May 2017 18:36:12 -0500 Subject: [PATCH 01/13] Inherit process from Swift --- CONTRIBUTING.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..170599e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Hubot Evolution Process + +[all-proposals]: https://github.com/hubotio/evolution/pulls?utf8=%E2%9C%93&q=is%3Apr +[chat]: https://hubot-slackin.herokuapp.com/ + +This document outlines how a Hubot feature grows from a rough idea into something that can improve workflows for millions of developers. + +This process covers all changes to Hubot, such as new features or adding, changing, or removing any APIs (no matter how small). Smaller changes, such as bug fixes, optimizations, or other improvements can be contributed via the [normal contribution process](https://github/github/hubot/blob/master/CONTRIBUTING.md) on the relevant repository. + +## Goals + +This process aims to leverage the collective ideas, insights, and experience of the community to improve the Hubot project and ecosystem. Its two primary goals are: + +* Engage the wider community in the ongoing evolution of Hubot, and +* Maintain the vision and conceptual coherence of Hubot. + +There is a natural tension between these two goals. Open evolution processes are, by nature, chaotic. Yet, maintaining a coherent vision requires some level of coordination. This process aims to strike a balance that best serves the entire Hubot ecosystem. + +## Participation + +Everyone is welcome to propose, discuss, and review ideas to improve Hubot. + +The Hubot maintainers are responsible for the strategic direction of Hubot. Maintainers initiate, participate in, and manage the public review of proposals and have the authority to accept or reject changes to Hubot. + +## How to propose a change + +1. **Check prior proposals**: many ideas come up frequently, and may either be in active discussion, or may have been discussed and rejected. Please check the [list of proposals][all-proposals] before proposing something new. +1. **Consider the goals of the upcoming release**: Each major release is focused on a [specific set of goals](README.md) described early in the release cycle. When proposing a change, please consider how your proposal fits in with the larger goals of the upcoming release. Proposals that are out of scope may still be considered, but will likely be postponed. +1. **Socialize the idea**: Before starting the review process, it's helpful to gauge interest from the community. Ideally, the idea would have come up in a discussion in another issue or in [chat][] and the consensus was to start an evolution proposal. +1. **Develop the proposal**: open a pull request with a rough sketch of the proposal using the [proposal template](template.md) in the [_drafts](https://github.com/hubotio/evolution/new/master/_drafts) directory. Prototyping an implementation and its uses along with the proposal is encouraged, because it helps ensure both technical feasibility of the proposal as well as validating that the proposal solves the problems it is meant to solve. +1. **Request a review**: When you are ready for feedback from the Hubot community, change the frontmatter in your proposal from `status: in-progress` to `status: ready-for-review`. +1. **Address feedback**: be responsive to questions and feedback about the proposal. When the proposal is sufficiently detailed and clear, and addresses feedback from earlier discussions of the idea, the `accepted` label will be added and a maintainer will be assigned to manage the review. + +## Review process + +When you change the frontmatter in your proposal from `status: in-progress` to `status: ready-for-review`, a message will be posted in the [#evolution channel in chat][chat] requesting feedback from the community. + +Reviews should usually be completed in a single week, but can run longer for particularly large or complex proposals. To avoid delays, it is important that the proposal authors be available to answer questions, address feedback, and clarify their intent during the review period. + +After feedback from the community has been gathered, the maintainers will make a decision on whether to `accept` or `reject` the proposal. + +## Proposal states + +A proposal can be in one of several states: + +* `in-progress`: The authors are still working on the proposal and are not yet ready for review. +* `ready-for-review`: The proposal is ready for review and comments from the community. +* `withdrawn`: The proposal has been withdrawn by the original submitter. +* `deferred`: Consideration of the proposal has been deferred because it does not meet the [goals of the upcoming release](README.md). Deferred proposals will be reconsidered when scoping the next major release. +* `accepted`: The proposal has been accepted and is either awaiting implementation or is actively being implemented. +* `rejected`: The proposal has been considered and rejected. +* `implemented`: The proposal has been implemented. Add the `version` to the frontmatter of the proposal and merge the pull request. From f6e7b394cfdf8805ee788d2d91006bfe9263159e Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sat, 20 May 2017 09:01:15 -0500 Subject: [PATCH 02/13] Add template --- template.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 template.md diff --git a/template.md b/template.md new file mode 100644 index 0000000..3bc8bae --- /dev/null +++ b/template.md @@ -0,0 +1,27 @@ +--- +status: in-progress +--- + +# Feature name + +> A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing. + +## Motivation + +> Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to implement, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help developers create better workflows. Include any links to Issues or Pull Requests where the need for this feature came up. + +## Proposed solution + +> Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds. + +## Detailed design + +> Describe the design of the solution in detail. The detail in this section should be sufficient for someone who is *not* one of the authors to be able to reasonably implement the feature. + +## Backward compatibility + +> Describe how this change affects compatibility with existing community packages. Will they break? Will they produce different behavior? If "yes" to either of these, is it possible to support the old behavior alongside the new behavior? Can scripts be written in a way that they work before and after this change? + +## Alternatives considered + +> Describe alternative approaches to addressing the same problem, and why you chose this approach instead. From b2a34261afbc06943e05b72897239a59360d11b4 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sat, 20 May 2017 09:18:46 -0500 Subject: [PATCH 03/13] Change status name --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 170599e..a81e7f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,12 +28,12 @@ The Hubot maintainers are responsible for the strategic direction of Hubot. Main 1. **Consider the goals of the upcoming release**: Each major release is focused on a [specific set of goals](README.md) described early in the release cycle. When proposing a change, please consider how your proposal fits in with the larger goals of the upcoming release. Proposals that are out of scope may still be considered, but will likely be postponed. 1. **Socialize the idea**: Before starting the review process, it's helpful to gauge interest from the community. Ideally, the idea would have come up in a discussion in another issue or in [chat][] and the consensus was to start an evolution proposal. 1. **Develop the proposal**: open a pull request with a rough sketch of the proposal using the [proposal template](template.md) in the [_drafts](https://github.com/hubotio/evolution/new/master/_drafts) directory. Prototyping an implementation and its uses along with the proposal is encouraged, because it helps ensure both technical feasibility of the proposal as well as validating that the proposal solves the problems it is meant to solve. -1. **Request a review**: When you are ready for feedback from the Hubot community, change the frontmatter in your proposal from `status: in-progress` to `status: ready-for-review`. +1. **Request a review**: When you are ready for feedback from the Hubot community, change the frontmatter in your proposal from `status: in-progress` to `status: in-review`. 1. **Address feedback**: be responsive to questions and feedback about the proposal. When the proposal is sufficiently detailed and clear, and addresses feedback from earlier discussions of the idea, the `accepted` label will be added and a maintainer will be assigned to manage the review. ## Review process -When you change the frontmatter in your proposal from `status: in-progress` to `status: ready-for-review`, a message will be posted in the [#evolution channel in chat][chat] requesting feedback from the community. +When you change the frontmatter in your proposal from `status: in-progress` to `status: in-review`, a message will be posted in the [#evolution channel in chat][chat] requesting feedback from the community. Reviews should usually be completed in a single week, but can run longer for particularly large or complex proposals. To avoid delays, it is important that the proposal authors be available to answer questions, address feedback, and clarify their intent during the review period. @@ -44,7 +44,7 @@ After feedback from the community has been gathered, the maintainers will make a A proposal can be in one of several states: * `in-progress`: The authors are still working on the proposal and are not yet ready for review. -* `ready-for-review`: The proposal is ready for review and comments from the community. +* `in-review`: The proposal is ready for review and comments from the community. * `withdrawn`: The proposal has been withdrawn by the original submitter. * `deferred`: Consideration of the proposal has been deferred because it does not meet the [goals of the upcoming release](README.md). Deferred proposals will be reconsidered when scoping the next major release. * `accepted`: The proposal has been accepted and is either awaiting implementation or is actively being implemented. From 82ef75d09ac12f746df4c702fe17da8632f749df Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sat, 20 May 2017 09:19:40 -0500 Subject: [PATCH 04/13] Author is responsible for implementation --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a81e7f6..413aa34 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,6 +39,8 @@ Reviews should usually be completed in a single week, but can run longer for par After feedback from the community has been gathered, the maintainers will make a decision on whether to `accept` or `reject` the proposal. +Once a proposal has been accepted, it is usually up to the proposal author to implement it or discuss with the maintainers who will lead the implementation. + ## Proposal states A proposal can be in one of several states: From b73e0eb5cd378f7e23fe7dfc58f2501b551e06d1 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sat, 20 May 2017 09:26:23 -0500 Subject: [PATCH 05/13] File naming and when to merge --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 413aa34..2405a09 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,7 +39,9 @@ Reviews should usually be completed in a single week, but can run longer for par After feedback from the community has been gathered, the maintainers will make a decision on whether to `accept` or `reject` the proposal. -Once a proposal has been accepted, it is usually up to the proposal author to implement it or discuss with the maintainers who will lead the implementation. +Once a proposal has been accepted, the file should be renamed to `proposals/###-feature-name.md`, where `###` is the Pull Request number. It is usually up to the proposal author to implement it or discuss with the maintainers who will lead the implementation. + +Once a proposal has been implemented, the Pull Request will be merged. ## Proposal states From 94f8fb291e51929ea9dd5b4aff2d905e43df2a5c Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sat, 20 May 2017 09:26:32 -0500 Subject: [PATCH 06/13] Consistent capitalization --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2405a09..3967311 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,7 @@ The Hubot maintainers are responsible for the strategic direction of Hubot. Main 1. **Check prior proposals**: many ideas come up frequently, and may either be in active discussion, or may have been discussed and rejected. Please check the [list of proposals][all-proposals] before proposing something new. 1. **Consider the goals of the upcoming release**: Each major release is focused on a [specific set of goals](README.md) described early in the release cycle. When proposing a change, please consider how your proposal fits in with the larger goals of the upcoming release. Proposals that are out of scope may still be considered, but will likely be postponed. 1. **Socialize the idea**: Before starting the review process, it's helpful to gauge interest from the community. Ideally, the idea would have come up in a discussion in another issue or in [chat][] and the consensus was to start an evolution proposal. -1. **Develop the proposal**: open a pull request with a rough sketch of the proposal using the [proposal template](template.md) in the [_drafts](https://github.com/hubotio/evolution/new/master/_drafts) directory. Prototyping an implementation and its uses along with the proposal is encouraged, because it helps ensure both technical feasibility of the proposal as well as validating that the proposal solves the problems it is meant to solve. +1. **Develop the proposal**: open a Pull Request with a rough sketch of the proposal using the [proposal template](template.md) in the [_drafts](https://github.com/hubotio/evolution/new/master/_drafts) directory. Prototyping an implementation and its uses along with the proposal is encouraged, because it helps ensure both technical feasibility of the proposal as well as validating that the proposal solves the problems it is meant to solve. 1. **Request a review**: When you are ready for feedback from the Hubot community, change the frontmatter in your proposal from `status: in-progress` to `status: in-review`. 1. **Address feedback**: be responsive to questions and feedback about the proposal. When the proposal is sufficiently detailed and clear, and addresses feedback from earlier discussions of the idea, the `accepted` label will be added and a maintainer will be assigned to manage the review. @@ -53,4 +53,4 @@ A proposal can be in one of several states: * `deferred`: Consideration of the proposal has been deferred because it does not meet the [goals of the upcoming release](README.md). Deferred proposals will be reconsidered when scoping the next major release. * `accepted`: The proposal has been accepted and is either awaiting implementation or is actively being implemented. * `rejected`: The proposal has been considered and rejected. -* `implemented`: The proposal has been implemented. Add the `version` to the frontmatter of the proposal and merge the pull request. +* `implemented`: The proposal has been implemented. Add the `version` to the frontmatter of the proposal and merge the Pull Request. From 533f5784d8801083cd3df8a1ebdbb2c9e37f8dfc Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sat, 20 May 2017 19:39:01 -0500 Subject: [PATCH 07/13] Add state config This is for https://github.com/integration/state, which will ensure that each Issue and Pull Request is in a unique state. --- .github/state.yml | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 .github/state.yml diff --git a/.github/state.yml b/.github/state.yml new file mode 100644 index 0000000..0b67305 --- /dev/null +++ b/.github/state.yml @@ -0,0 +1,8 @@ +states: +- in-progress +- in-review +- withdrawn +- deferred +- accepted +- rejected +- implemented From ae5bacc6649f011bf9523b7cb9f2df62578faaf3 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sat, 20 May 2017 19:40:14 -0500 Subject: [PATCH 08/13] Update state.yml --- .github/state.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/state.yml b/.github/state.yml index 0b67305..a80d0a3 100644 --- a/.github/state.yml +++ b/.github/state.yml @@ -1,3 +1,4 @@ +# Configuration for Probot state plugin - https://github.com/probot/state states: - in-progress - in-review From f46f10886c0135a9abace8e153592faea0dd534a Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sun, 21 May 2017 09:59:19 -0500 Subject: [PATCH 09/13] Add project, update states --- .github/state.yml | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/state.yml b/.github/state.yml index a80d0a3..fb0d787 100644 --- a/.github/state.yml +++ b/.github/state.yml @@ -1,9 +1,11 @@ # Configuration for Probot state plugin - https://github.com/probot/state states: -- in-progress -- in-review -- withdrawn -- deferred -- accepted -- rejected -- implemented +- In Progress +- In Review +- Withdrawn +- Deferred +- Accepted +- Rejected +- Implemented + +project: Proposals From 35881a6866e869f357c8da135d917c346192f61d Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sun, 21 May 2017 10:09:34 -0500 Subject: [PATCH 10/13] Link to project board --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3967311..6cfe01f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Hubot Evolution Process -[all-proposals]: https://github.com/hubotio/evolution/pulls?utf8=%E2%9C%93&q=is%3Apr +[all-proposals]: https://github.com/hubotio/evolution/projects/1 [chat]: https://hubot-slackin.herokuapp.com/ This document outlines how a Hubot feature grows from a rough idea into something that can improve workflows for millions of developers. From bb25c278caf8d92b325e6abbfbe415a0945214e4 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sun, 21 May 2017 10:16:44 -0500 Subject: [PATCH 11/13] Update states --- CONTRIBUTING.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6cfe01f..1958a02 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,12 +28,12 @@ The Hubot maintainers are responsible for the strategic direction of Hubot. Main 1. **Consider the goals of the upcoming release**: Each major release is focused on a [specific set of goals](README.md) described early in the release cycle. When proposing a change, please consider how your proposal fits in with the larger goals of the upcoming release. Proposals that are out of scope may still be considered, but will likely be postponed. 1. **Socialize the idea**: Before starting the review process, it's helpful to gauge interest from the community. Ideally, the idea would have come up in a discussion in another issue or in [chat][] and the consensus was to start an evolution proposal. 1. **Develop the proposal**: open a Pull Request with a rough sketch of the proposal using the [proposal template](template.md) in the [_drafts](https://github.com/hubotio/evolution/new/master/_drafts) directory. Prototyping an implementation and its uses along with the proposal is encouraged, because it helps ensure both technical feasibility of the proposal as well as validating that the proposal solves the problems it is meant to solve. -1. **Request a review**: When you are ready for feedback from the Hubot community, change the frontmatter in your proposal from `status: in-progress` to `status: in-review`. +1. **Request a review**: When you are ready for feedback from the Hubot community, change the frontmatter in your proposal from `state: In Progress` to `state: In Review`. 1. **Address feedback**: be responsive to questions and feedback about the proposal. When the proposal is sufficiently detailed and clear, and addresses feedback from earlier discussions of the idea, the `accepted` label will be added and a maintainer will be assigned to manage the review. ## Review process -When you change the frontmatter in your proposal from `status: in-progress` to `status: in-review`, a message will be posted in the [#evolution channel in chat][chat] requesting feedback from the community. +When you change the frontmatter in your proposal from `state: In Progress` to `state: In Review`, a message will be posted in the [#evolution channel in chat][chat] requesting feedback from the community. Reviews should usually be completed in a single week, but can run longer for particularly large or complex proposals. To avoid delays, it is important that the proposal authors be available to answer questions, address feedback, and clarify their intent during the review period. @@ -47,10 +47,10 @@ Once a proposal has been implemented, the Pull Request will be merged. A proposal can be in one of several states: -* `in-progress`: The authors are still working on the proposal and are not yet ready for review. -* `in-review`: The proposal is ready for review and comments from the community. -* `withdrawn`: The proposal has been withdrawn by the original submitter. -* `deferred`: Consideration of the proposal has been deferred because it does not meet the [goals of the upcoming release](README.md). Deferred proposals will be reconsidered when scoping the next major release. -* `accepted`: The proposal has been accepted and is either awaiting implementation or is actively being implemented. -* `rejected`: The proposal has been considered and rejected. -* `implemented`: The proposal has been implemented. Add the `version` to the frontmatter of the proposal and merge the Pull Request. +* **In Progress**: The authors are still working on the proposal and are not yet ready for review. +* **In Review**: The proposal is ready for review and comments from the community. +* **Withdrawn**: The proposal has been withdrawn by the original submitter. +* **Deferred**: Consideration of the proposal has been deferred because it does not meet the [goals of the upcoming release](README.md). Deferred proposals will be reconsidered when scoping the next major release. +* **Accepted**: The proposal has been accepted and is either awaiting implementation or is actively being implemented. +* **Rejected**: The proposal has been considered and rejected. +* **Implemented**: The proposal has been implemented. Add the `version` to the frontmatter of the proposal and merge the Pull Request. From 51a871970178175a558553bf5821647a1d6be993 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sun, 21 May 2017 10:17:10 -0500 Subject: [PATCH 12/13] Update state in template --- template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/template.md b/template.md index 3bc8bae..343ef5a 100644 --- a/template.md +++ b/template.md @@ -1,5 +1,5 @@ --- -status: in-progress +state: In Progress --- # Feature name From dd134791a14053ae6c4800b3589a883f697d7d20 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sun, 21 May 2017 10:19:43 -0500 Subject: [PATCH 13/13] Link to project board --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 33f6f2c..9d65826 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ This repository tracks the ongoing evolution of Hubot. It contains: * Goals for upcoming releases. Up next: [3.0](#hubot-3.0) -* [Proposals](https://github.com/hubotio/evolution/pulls) to change Hubot +* [Proposals](https://github.com/hubotio/evolution/projects/1) to change Hubot * The [process](CONTRIBUTING.md) that governs the evolution of Hubot. This document describes goals on a per-release basis, usually listing minor releases adding to the currently shipping version and one major release out. Each release will have many smaller features or changes independent of these larger goals, and not all goals are reached for each release.