Repository files navigation

Raku/problem-solving repository is used for working on all issuesthat require discussion and/or consensus. This document describes theprocess in more detail.

Anyone is welcome to report a problem by creating a new issue. The issue shouldonlycontain the description of the actual problem (X of theXY). The issue youcreate 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 belonghere – only problems where consensus needs to exist but doesn't yet.For example, if everyone already agrees on the proper approach tosolving a problem, then that issue isn't appropriate for this repo(even if a few technical questions about the implementation stillneed to be worked out). As a more concrete example, bugs in theRakudo compiler should be reported inrakudo repository.

If someone opens an issue that doesn't belong in Problem Solving,then anyone with sufficient GitHub permissions to do so should closethe issue and either direct the user to the correct place to addressthis issue (e.g., the Rakudo repo) or open an issue themselves.

Anyone (including the person who opened the issue) cansubmit an initial proposal as a comment in reply to the issue.

To do so, start a comment with “Initial proposal:” and provide a short andclear description of the solution you're suggesting. Include just enoughdetails 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 otherrelated problems that will be affected by your solution.

By proposing a solution, you aretypically volunteering to implementthat solution. If you know that you won't be able to work on afull solution, pleasesay so when proposing that solution. Having ahero who will carry a solution though to implementation is oftenessential, but it is also important to hear out good heroless ideas.

After the initial proposal, everyone is encouraged to discuss the idea and pointout any flaws, implementation details, suggested changes, etc. thatthey might see. (Of course, both before and during step 3, peoplecan discuss the problem generally rather than a particular solution.)

In step 3, anyone can comment, but two people have an especiallyimportant role to play: the person who wrote the original proposaland theassignee for the issue.

Issues are assigned to corresponding devs (seethe list). The assignee's job isto help drive the process, provide vision, and assist everyoneinvolved. Assignees can provide feedback, ask for clarifications,suggest changes and so on as they see fit.

Assignees can provide feedback on an initial solution, provide guidanceabout what the full solution should include (e.g. what should becovered in the document, additional requirements, etc). They can alsoreject initial proposals at step 3 (though this shouldn't happen often).

If an assignee is pleased with the initial proposal, they can ask tosubmit a fullblown solution. Alternatively, if the person who suggestedthe solution feels they have received enough feedback, they can decide tosubmit a full solution. Either way, submitting a solution moves us to thenext step.

After a problem/solution has been discussed sufficiently, someone shouldsubmit 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 aninitial solution (as described in Step 2, above) and, typically, the PR wouldbe written by the same user who wrote that initial solution.

However, neither of these part of the above isabsolutely required. Forexample, if someone writes an initial solution but doesn't have time (or nolonger has time) to work on implementing the solution, it's fine for someonewho does have time to submit the PR. Similarly, if an initial solution hasbeen discussed without anyoneformally 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 otherusers 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 writtenby the same person.

The PR should act as a documentation for the solution and should provideall details that are required to implement the solution. Keep your documentconsistent with other files in the solutions directory (naming, directorystructure, markup and so on).

At this point, anyone can provide feedback on the full solution and, ifdesired, the PR author can revise the PR based on that feedback.

Once someone has submitted a PR, it can be resolved in one of 4 ways:

1. Consensus acceptance
2. Speedy acceptance
3. Acceptance without consensus
4. Non-acceptance

The most common way for a proposal to be accepted is for the discussion toproceed to a point where a consensus exists in favor of the solution. Aconsensus does not requireunanimity, but it should be clear that theRaku community as a whole supports the solution. In particular, if 14 dayspass between the time when the PR (or the latest revision of the PR, if it'sedited) was proposed and none of thereviewers (listed below)have objected, then the proposer of the PR can use their judgement to determinewhether consensus exists. However, if any of the reviewers objects to the PR'ssolution or 14 days have not yet passed, then consensus doesnot supportthat solution.

If all reviewers approve a solution, then it can be accepted even if 14 dayshave not passed.

Invery rare cases, a PR's solution can be accepted even when the Rakucommunity cannot reach consensus. When the Problem Solving process was firstadopted, the way Raku solved problems when consensus couldn't be reached was byan action by the Benevolent Dictator for Life (Larry Wall). After theRakuSteering Council Codewas adopted, the process for resolving deadlock shifted to the RSC asdescribed in that document. In either case, this power should be exercisedonly as a last resort and in extremely exceptional cases.

If a solution is not accepted by any of the methods described above, thenit is not accepted. Arguably, this isn't a resolution at all – the problemremains unsolved and the issue stays open. But that particular solutionhas failed to gain acceptance (though, of course, a different solution oreven a revised version of the same solution could later be accepted).

• If any of the merged solutions needs an adjustment, the process shouldstart from the beginning. That is, an issue should be filed statingthe problem with the current solution, and the process continues asnormal. PRs are allowed to change, modify and shadow existingsolutions.
• Assignees are allowed to call for a “shortcut” to any problem, inwhich case the solution is applied directly without going throughthe whole process.
• Non-functional changes to existing solutions automatically gothrough a shortcut (typos, grammar, formatting, etc.), just submita PR right away.
• If a shortcut receives any criticism from the correspondingdevelopment team or other affected parties, it can be reverted andthe full formal process should begin.
• Passing the assignee status is allowed provided that the receivingparty agrees. One-time assignees are allowed through this process.
• People are allowed to be assigned to their own PRs.

File ameta issue if you want to create a new label or if you wantto be added as a responsible dev.

• meta – changes to theproblem-solving repo and this document
  • @codesections
• language – changes to theRaku language
  • –
• rakudo – big changes toRakudo
  • –
• moarvm – big changes toMoarVM
  • –
• documentation – big changes toRaku documentation and other learningresources
  • @coke
• unicode – Unicode and encoding/decoding
  • @samcv
• infrastructure - servers, hosting, cloud, monitoring, backup and automation
  • @rba
  • @maettu
• fallback – if no other label fits
  • @codesections

File ameta issue if you want to be added to this list.

• @codesections
• @FCO
• @JJ
• @lizmat
• @maettu
• @masak
• @MasterDuke17
• @rba
• @samcv
• @timo
• @tony-o
• @vrurg