From e43a7a59a438a9f8a71f47cb9a01b362b3d2e076 Mon Sep 17 00:00:00 2001 From: Daniel Sockwell Date: Fri, 2 Jul 2021 17:56:21 -0400 Subject: [PATCH 1/4] clarify PS process in README This is an attempted solution to #272 as described in that issue. In particular, it is intended to clarify the existing process without adding any substantive changes. --- README.md | 190 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 118 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index e94219c..13ff804 100644 --- a/README.md +++ b/README.md @@ -4,104 +4,153 @@ that require discussion and/or consensus. This document describes the process in more detail. +## The Problem-Solving Process +### Step 1: Reporting a problem -## Reporting a problem - -Anyone is welcome to create a new issue. The ticket should *only* +Anyone is welcome to create a new issue. The issue should *only* contain the description of the actual problem (X of the -[XY](https://en.wikipedia.org/wiki/XY_problem)). It is advised that -you start your ticket with a short description of the problem and -include more details afterwards. +[XY](https://en.wikipedia.org/wiki/XY_problem)). The issue you +create should start with a short description of the problem, +followed by any additional details, if needed. This repository has broad scope, but not all problems belong -here. For example, bugs in the Rakudo compiler should be reported in +here – only problems where consensus needs to exist but doesn't yet. +For example, if everyone already agrees on the proper approach to +solving a problem, then that issue isn't appropriate for this repo +(even if a few technical questions about the implementation still +need to be worked out). As a more concrete example, bugs in the +Rakudo compiler should be reported in [rakudo repository](https://github.com/rakudo/rakudo/issues). -## Initial proposal +If someone opens an issue that doesn't belong in Problem Solving, +then anyone with sufficient GitHub permissions to do so should close +the issue and direct the user to the correct place to address that +issue (e.g., the Rakudo repo). + +### Step 2: Initial proposed solution -Anyone is welcome to submit an initial proposal as a comment. Start -your comment with “Initial proposal:” and follow with a short and -clear description of the approach that can be used to resolve the -problem. Include just enough details to paint the general picture and -refrain from writing too much (which will be required for the next -step, but not now). +Anyone (including the person who opened the issue) can +submit an initial proposal as a comment in reply to the issue. -Good solutions resolve more than one problem, so link all other +To do so, start a comment with “Initial proposal:” and provide a short and +clear description of the solution you're suggesting. Include just enough +details to paint the general picture and refrain from writing too much +(which will be required for the next step, but not now). + +Good solutions may resolve more than one problem: if so, link all other related problems that will be affected by your solution. -If you know that you won't be able to work on a full solution, please -indicate so in your comment. Having a hero is often more important -than having a good idea, but it is also important to hear out good -heroless ideas. +By proposing a solution, you are _typically_ volunteering to implement +that solution. If you know that you won't be able to work on a +full solution, please **say so when proposing that solution**. Having a +hero who will carry a solution though to implementation is often +essential, but it is also important to hear out good heroless ideas. + +### Step 3: Discussion of the proposal +After the initial proposal, everyone should discuss the idea and point +out any flaws, implementation details, suggested changes, etc. that +they might see. (Of course, both before and during step 3, people +can discuss the problem generally rather than a particular solution.) -### Assignees and their role +In step 3, anyone can comment, but two people have as especially +important role to play: the person who wrote the original proposal +and the _assignee_ for the issue. -Issues and PRs are labeled and assigned to corresponding devs (see -[the list](#labels-and-responsible-devs)). The task of the assignee is -to drive the process, provide vision and assist everyone +#### Assignees + +Issues are assigned to corresponding devs (see +[the list](#labels-and-responsible-devs)). The assignee's job is +to help drive the process, provide vision, and assist everyone involved. Assignees can provide feedback, ask for clarifications, -suggest changes and so on as they see fit. They can also reject -initial proposals early. +suggest changes and so on as they see fit. -Labels and assignees are managed in different ways (automatically -by a bot, manually, self-assignment, etc). +Assignees can provide feedback on an initial solution, provide guidance +about what the full solution should include (e.g. what should be +covered in the document, additional requirements, etc). They can also +reject initial proposals at step 3 (though this shouldn't happen often). If an assignee is pleased with the initial proposal, they can ask to -submit a fullblown solution. This moves us to the next step. Assignees -should provide their expectations of the solution (e.g. what should be -covered in the document, additional requirements, etc). +submit a fullblown solution. Alternatively, if the person who suggested +the solution feels they have received enough feedback, they can decide to +submit a full solution. Either way, submitting a solution moves us to the +next step. -## Submitting a solution +### Step 4: Submitting a full solution -PRs can only be submitted once all previous stages are completed. PRs -should be submitted in `Raku/problem-solving` repository. The -document in the PR should act as a documentation for the solution (as -it will also be read later after it is accepted). This time all -details should be provided. Keep your document consistent with other -files in the repository (naming, directory structure, markup and so -on). +After a problem/solution has been discussed sufficiently, someone should +submit a Pull Request with a detailed proposal that would solve the problem. +This PR should add a document to the "solutions" directory in this repo. +Typically, the solution will come after a user has officially proposed an +initial solution (as described in Step 2, above) and, typically, the PR would +be written by the same user who wrote that initial solution. -Assignees will request changes that are necessary to finalize the -solution. Note that this process may require an actual implementation -(if applicable) and other efforts (possibly in other repos) if so is -required by the assignee. +However, neither of these part of the above is _absolutely_ required. For +example, if someone writes an initial solution but doesn't have time (or no +longer has time) to work on implementing the solution, it's fine for someone +who does have time to submit the PR. Similarly, if an initial solution has +been discussed without anyone _formally_ writing an "initial solution" comment, +someone who was involved in that discussion can step forward and draft a PR. +(This can sometimes happen when one user has a partial solution and other +users add to it without anyone drafting a formal initial solution.) That said, +it's still better to have a written initial solution and for the PR to be written +by the same person. -If there are common principles that are used for a particular label, -assignees are welcome to compose a document in order to avoid -repeating themselves. +The PR should act as a documentation for the solution and should provide +all details that are required to implement the solution. Keep your document +consistent with other files in the solutions directory (naming, directory +structure, markup and so on). -Note that all people (even non-devs) who have enough experience in -affected areas are welcome to provide feedback. That being said, the -assignee has the final word on decisions in the issue/PR, so they are -free to engage in discussions as they see fit. In rare cases they can -moderate/lock the discussion if doing so is unavoidable. +At this point, anyone can provide feedback on the full solution and, if +desired, the PR author can revise the PR based on that feedback. -Once the assignee is happy with the proposal, the process moves to the -next step. +### Step 5: Solution resolution -## Acceptance +Once someone has submitted a PR, it can be resolved in one of 4 ways: -A review is requested from all of the reviewers (see -[the list](#reviewers)). This step exists to ensure peer-review and to -notify the devs of the major upcoming changes. By approving a PR the -dev confirms that they reviewed and understood the proposal, and that -they are OK with it. This is also the last chance to express concerns -and present feedback (though it is encouraged to do that before this -step is reached). +1. Consensus acceptance +2. Speedy acceptance +3. Acceptance without consensus +4. Non-acceptance -It is expected that all reviewers will understand the reasoning of the -solution and in the end all of them will approve the PR. This may -require time, discussion, and minor adjustments, but if it happens -that the discussion doesn't lead to mutual understanding, the BDFL may -step in. +#### Consensus acceptance -This is the final step. Once the PR is merged, it is expected that -corresponding efforts (e.g. PRs in other repos) are merged too, and -the future work is already outlined. This is the last step. +The most common way for a proposal to be accepted is for the discussion to +proceed to a point where a consensus exists in favor of the solution. A +consensus does not require _unanimity_, but it should be clear that the +Raku community as a whole supports the solution. In particular, if 14 days +pass between the time when the PR (or the latest revision of the PR, if it's +edited) was proposed and none of the [reviewers](#reviewers) (listed below) +have objected, then the proposer of the PR can use their judgement to determine +whether consensus exists. However, if any of the reviewers objects to the PR's +solution or 14 days have not yet passed, then consensus does *not* support +that solution. +#### Speedy acceptance + +If all reviewers approve a solution, then it can be accepted even if 14 days +have not passed. + +#### Acceptance without consensus + +In **very** rare cases, a PR's solution can be accepted even when the Raku +community cannot reach consensus. When the Problem Solving process was first +adopted, the way Raku solved problems when consensus couldn't be reached was by +an action by the Benevolent Dictator for Life (Larry Wall). After the [Raku +Steering Council Code](https://github.com/Raku/Raku-Steering-Council/blob/main/papers/Raku_Steering_Council_Code.md) +was adopted, the process for resolving deadlock shifted to the RSC as +described in that document. In either case, this power should be exercised +only as a last resort and in extremely exceptional cases. + +#### Non-acceptance + +If a solution is not accepted by any of the methods described above, then +it is not accepted. Arguably, this isn't a resolution at all – the problem +remains unsolved and the issue stays open. But that particular solution +has failed to gain acceptance (though, of course, a different solution or +even a revised version of the same solution could later be accepted). ## Edge cases and other notes @@ -120,13 +169,10 @@ the future work is already outlined. This is the last step. * If a shortcut receives any criticism from the corresponding development team or other affected parties, it can be reverted and the full formal process should begin. -* If a reviewer does not respond in 14 days, they are removed from the - list of reviewers on that PR. * Passing the assignee status is allowed provided that the receiving party agrees. One-time assignees are allowed through this process. * People are allowed to be assigned to their own PRs. -* If everything else fails, BDFL can force any change as they - like, though this should only be used in exceptional cases. + ## Labels and responsible devs From fe9d5ca87635ce06db5ab8cdbf6fc4d4195be475 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Juli=C3=A1n=20Merelo=20Guerv=C3=B3s?= Date: Tue, 6 Jul 2021 16:16:16 +0200 Subject: [PATCH 2/4] Address some comments. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 13ff804..46399f1 100644 --- a/README.md +++ b/README.md @@ -48,12 +48,12 @@ essential, but it is also important to hear out good heroless ideas. ### Step 3: Discussion of the proposal -After the initial proposal, everyone should discuss the idea and point +After the initial proposal, everyone may discuss the idea and point out any flaws, implementation details, suggested changes, etc. that they might see. (Of course, both before and during step 3, people can discuss the problem generally rather than a particular solution.) -In step 3, anyone can comment, but two people have as especially +In step 3, anyone can comment, but two people have an especially important role to play: the person who wrote the original proposal and the _assignee_ for the issue. From a91a27444273d8ba13ea468a0bede007fba1ef3c Mon Sep 17 00:00:00 2001 From: Daniel Sockwell Date: Sun, 11 Jul 2021 10:55:57 -0400 Subject: [PATCH 3/4] Resolve remaining comments The remaining comments were mostly nits; this commit accepts them all. --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 46399f1..9b6efd1 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ process in more detail. ## The Problem-Solving Process ### Step 1: Reporting a problem -Anyone is welcome to create a new issue. The issue should *only* +Anyone is welcome to report a problem by creating a new issue. The issue should *only* contain the description of the actual problem (X of the [XY](https://en.wikipedia.org/wiki/XY_problem)). The issue you create should start with a short description of the problem, @@ -24,8 +24,8 @@ Rakudo compiler should be reported in If someone opens an issue that doesn't belong in Problem Solving, then anyone with sufficient GitHub permissions to do so should close -the issue and direct the user to the correct place to address that -issue (e.g., the Rakudo repo). +the issue and either direct the user to the correct place to address +this issue (e.g., the Rakudo repo) or open an issue themselves. ### Step 2: Initial proposed solution @@ -48,7 +48,7 @@ essential, but it is also important to hear out good heroless ideas. ### Step 3: Discussion of the proposal -After the initial proposal, everyone may discuss the idea and point +After the initial proposal, everyone is encoraged to discuss the idea and point out any flaws, implementation details, suggested changes, etc. that they might see. (Of course, both before and during step 3, people can discuss the problem generally rather than a particular solution.) From e84670523fc0bb5df6533a2f71848d88c2f0183c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Juli=C3=A1n=20Merelo=20Guerv=C3=B3s?= Date: Sun, 11 Jul 2021 17:03:27 +0200 Subject: [PATCH 4/4] :pencil2: --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9b6efd1..68659aa 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ essential, but it is also important to hear out good heroless ideas. ### Step 3: Discussion of the proposal -After the initial proposal, everyone is encoraged to discuss the idea and point +After the initial proposal, everyone is encouraged to discuss the idea and point out any flaws, implementation details, suggested changes, etc. that they might see. (Of course, both before and during step 3, people can discuss the problem generally rather than a particular solution.)