├── .github ├── CODEOWNERS └── ISSUE_TEMPLATE │ ├── issue-template-documentation.md │ ├── issue-template-fallback.md │ ├── issue-template-infrastructure.md │ ├── issue-template-language.md │ ├── issue-template-meta.md │ ├── issue-template-moarvm.md │ ├── issue-template-rakudo.md │ └── issue-template-unicode.md ├── .gitignore ├── LICENSE ├── README.md └── solutions ├── documentation ├── front-matter-for-routines.md └── search-categories.md ├── language ├── Add-head-skip-tail-subs.md ├── Path-to-Raku.md ├── SWOT-to-Raku.md └── Windows-process-argument-quoting.md ├── meta ├── Problem-Solving.md ├── TheRakuFoundation.md ├── coc_incident_response_guide.md ├── code_of_conduct.md ├── conf.raku.org ├── move-repo-to-raku.md └── sunsetting-p6c-cpan.md └── rakudo ├── Old-Issue-Tracker-Dismantling-Plan.md └── Use-main-branch.md /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @codesections 2 | solutions/meta @codesections 3 | #solutions/language – 4 | #solutions/rakudo – 5 | #solutions/moarvm – 6 | #solutions/documentation - 7 | solutions/unicode @samcv 8 | solutions/infrastructure @rba 9 | solutions/fallback @codesections 10 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/issue-template-documentation.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report a documentation problem 3 | about: Big changes to Raku documentation and other learning resources 4 | title: '' 5 | labels: 'documentation' 6 | assignees: 'coke' 7 | 8 | --- 9 | 10 | 11 | … 12 | 13 | 14 | … 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/issue-template-fallback.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report another problem 3 | about: Basic template for reporting problems (if no other label fits) 4 | title: '' 5 | labels: 'fallback' 6 | assignees: 'codesections' 7 | 8 | --- 9 | 10 | 11 | … 12 | 13 | 14 | … 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/issue-template-infrastructure.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report an infrastructure problem 3 | about: Servers, hosting, cloud, monitoring, backup and automation 4 | title: '' 5 | labels: 'infrastructure' 6 | assignees: 'rba' 7 | 8 | --- 9 | 10 | 11 | … 12 | 13 | 14 | … 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/issue-template-language.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report a language problem 3 | about: Changes to the Raku language 4 | title: '' 5 | labels: 'language' 6 | assignees: 7 | 8 | --- 9 | 10 | 11 | … 12 | 13 | 14 | … 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/issue-template-meta.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report a meta problem 3 | about: Changes to the problem-solving repo and this document 4 | title: '' 5 | labels: 'meta' 6 | assignees: 'codesections' 7 | 8 | --- 9 | 10 | 11 | … 12 | 13 | 14 | … 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/issue-template-moarvm.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report a moarvm problem 3 | about: Big changes to MoarVM 4 | title: '' 5 | labels: 'rakudo' 6 | assignees: 7 | 8 | --- 9 | 10 | 11 | … 12 | 13 | 14 | … 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/issue-template-rakudo.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report a rakudo problem 3 | about: Big changes to Rakudo 4 | title: '' 5 | labels: 'rakudo' 6 | assignees: 7 | 8 | --- 9 | 10 | 11 | … 12 | 13 | 14 | … 15 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/issue-template-unicode.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Report a unicode problem 3 | about: Unicode and encoding/decoding 4 | title: '' 5 | labels: 'unicode' 6 | assignees: 'samcv' 7 | 8 | --- 9 | 10 | 11 | … 12 | 13 | 14 | … 15 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *~ -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The Artistic License 2.0 2 | 3 | Copyright (c) 2000-2006, The Perl Foundation. 4 | 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | This license establishes the terms under which a given free software 11 | Package may be copied, modified, distributed, and/or redistributed. 12 | The intent is that the Copyright Holder maintains some artistic 13 | control over the development of that Package while still keeping the 14 | Package available as open source and free software. 15 | 16 | You are always permitted to make arrangements wholly outside of this 17 | license directly with the Copyright Holder of a given Package. If the 18 | terms of this license do not permit the full use that you propose to 19 | make of the Package, you should contact the Copyright Holder and seek 20 | a different licensing arrangement. 21 | 22 | Definitions 23 | 24 | "Copyright Holder" means the individual(s) or organization(s) 25 | named in the copyright notice for the entire Package. 26 | 27 | "Contributor" means any party that has contributed code or other 28 | material to the Package, in accordance with the Copyright Holder's 29 | procedures. 30 | 31 | "You" and "your" means any person who would like to copy, 32 | distribute, or modify the Package. 33 | 34 | "Package" means the collection of files distributed by the 35 | Copyright Holder, and derivatives of that collection and/or of 36 | those files. A given Package may consist of either the Standard 37 | Version, or a Modified Version. 38 | 39 | "Distribute" means providing a copy of the Package or making it 40 | accessible to anyone else, or in the case of a company or 41 | organization, to others outside of your company or organization. 42 | 43 | "Distributor Fee" means any fee that you charge for Distributing 44 | this Package or providing support for this Package to another 45 | party. It does not mean licensing fees. 46 | 47 | "Standard Version" refers to the Package if it has not been 48 | modified, or has been modified only in ways explicitly requested 49 | by the Copyright Holder. 50 | 51 | "Modified Version" means the Package, if it has been changed, and 52 | such changes were not explicitly requested by the Copyright 53 | Holder. 54 | 55 | "Original License" means this Artistic License as Distributed with 56 | the Standard Version of the Package, in its current version or as 57 | it may be modified by The Perl Foundation in the future. 58 | 59 | "Source" form means the source code, documentation source, and 60 | configuration files for the Package. 61 | 62 | "Compiled" form means the compiled bytecode, object code, binary, 63 | or any other form resulting from mechanical transformation or 64 | translation of the Source form. 65 | 66 | 67 | Permission for Use and Modification Without Distribution 68 | 69 | (1) You are permitted to use the Standard Version and create and use 70 | Modified Versions for any purpose without restriction, provided that 71 | you do not Distribute the Modified Version. 72 | 73 | 74 | Permissions for Redistribution of the Standard Version 75 | 76 | (2) You may Distribute verbatim copies of the Source form of the 77 | Standard Version of this Package in any medium without restriction, 78 | either gratis or for a Distributor Fee, provided that you duplicate 79 | all of the original copyright notices and associated disclaimers. At 80 | your discretion, such verbatim copies may or may not include a 81 | Compiled form of the Package. 82 | 83 | (3) You may apply any bug fixes, portability changes, and other 84 | modifications made available from the Copyright Holder. The resulting 85 | Package will still be considered the Standard Version, and as such 86 | will be subject to the Original License. 87 | 88 | 89 | Distribution of Modified Versions of the Package as Source 90 | 91 | (4) You may Distribute your Modified Version as Source (either gratis 92 | or for a Distributor Fee, and with or without a Compiled form of the 93 | Modified Version) provided that you clearly document how it differs 94 | from the Standard Version, including, but not limited to, documenting 95 | any non-standard features, executables, or modules, and provided that 96 | you do at least ONE of the following: 97 | 98 | (a) make the Modified Version available to the Copyright Holder 99 | of the Standard Version, under the Original License, so that the 100 | Copyright Holder may include your modifications in the Standard 101 | Version. 102 | 103 | (b) ensure that installation of your Modified Version does not 104 | prevent the user installing or running the Standard Version. In 105 | addition, the Modified Version must bear a name that is different 106 | from the name of the Standard Version. 107 | 108 | (c) allow anyone who receives a copy of the Modified Version to 109 | make the Source form of the Modified Version available to others 110 | under 111 | 112 | (i) the Original License or 113 | 114 | (ii) a license that permits the licensee to freely copy, 115 | modify and redistribute the Modified Version using the same 116 | licensing terms that apply to the copy that the licensee 117 | received, and requires that the Source form of the Modified 118 | Version, and of any works derived from it, be made freely 119 | available in that license fees are prohibited but Distributor 120 | Fees are allowed. 121 | 122 | 123 | Distribution of Compiled Forms of the Standard Version 124 | or Modified Versions without the Source 125 | 126 | (5) You may Distribute Compiled forms of the Standard Version without 127 | the Source, provided that you include complete instructions on how to 128 | get the Source of the Standard Version. Such instructions must be 129 | valid at the time of your distribution. If these instructions, at any 130 | time while you are carrying out such distribution, become invalid, you 131 | must provide new instructions on demand or cease further distribution. 132 | If you provide valid instructions or cease distribution within thirty 133 | days after you become aware that the instructions are invalid, then 134 | you do not forfeit any of your rights under this license. 135 | 136 | (6) You may Distribute a Modified Version in Compiled form without 137 | the Source, provided that you comply with Section 4 with respect to 138 | the Source of the Modified Version. 139 | 140 | 141 | Aggregating or Linking the Package 142 | 143 | (7) You may aggregate the Package (either the Standard Version or 144 | Modified Version) with other packages and Distribute the resulting 145 | aggregation provided that you do not charge a licensing fee for the 146 | Package. Distributor Fees are permitted, and licensing fees for other 147 | components in the aggregation are permitted. The terms of this license 148 | apply to the use and Distribution of the Standard or Modified Versions 149 | as included in the aggregation. 150 | 151 | (8) You are permitted to link Modified and Standard Versions with 152 | other works, to embed the Package in a larger work of your own, or to 153 | build stand-alone binary or bytecode versions of applications that 154 | include the Package, and Distribute the result without restriction, 155 | provided the result does not expose a direct interface to the Package. 156 | 157 | 158 | Items That are Not Considered Part of a Modified Version 159 | 160 | (9) Works (including, but not limited to, modules and scripts) that 161 | merely extend or make use of the Package, do not, by themselves, cause 162 | the Package to be a Modified Version. In addition, such works are not 163 | considered parts of the Package itself, and are not subject to the 164 | terms of this license. 165 | 166 | 167 | General Provisions 168 | 169 | (10) Any use, modification, and distribution of the Standard or 170 | Modified Versions is governed by this Artistic License. By using, 171 | modifying or distributing the Package, you accept this license. Do not 172 | use, modify, or distribute the Package, if you do not accept this 173 | license. 174 | 175 | (11) If your Modified Version has been derived from a Modified 176 | Version made by someone other than you, you are nevertheless required 177 | to ensure that your Modified Version complies with the requirements of 178 | this license. 179 | 180 | (12) This license does not grant you the right to use any trademark, 181 | service mark, tradename, or logo of the Copyright Holder. 182 | 183 | (13) This license includes the non-exclusive, worldwide, 184 | free-of-charge patent license to make, have made, use, offer to sell, 185 | sell, import and otherwise transfer the Package with respect to any 186 | patent claims licensable by the Copyright Holder that are necessarily 187 | infringed by the Package. If you institute patent litigation 188 | (including a cross-claim or counterclaim) against any party alleging 189 | that the Package constitutes direct or contributory patent 190 | infringement, then this Artistic License to you shall terminate on the 191 | date that such litigation is filed. 192 | 193 | (14) Disclaimer of Warranty: 194 | THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS 195 | IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED 196 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR 197 | NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL 198 | LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL 199 | BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL 200 | DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF 201 | ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 🦋 Problem Solving 2 | 3 | `Raku/problem-solving` repository is used for working on all issues 4 | that require discussion and/or consensus. This document describes the 5 | process in more detail. 6 | 7 | ## The Problem-Solving Process 8 | ### Step 1: Reporting a problem 9 | 10 | Anyone is welcome to report a problem by creating a new issue. The issue should *only* 11 | contain the description of the actual problem (X of the 12 | [XY](https://en.wikipedia.org/wiki/XY_problem)). The issue you 13 | create should start with a short description of the problem, 14 | followed by any additional details, if needed. 15 | 16 | This repository has broad scope, but not all problems belong 17 | here – only problems where consensus needs to exist but doesn't yet. 18 | For example, if everyone already agrees on the proper approach to 19 | solving a problem, then that issue isn't appropriate for this repo 20 | (even if a few technical questions about the implementation still 21 | need to be worked out). As a more concrete example, bugs in the 22 | Rakudo compiler should be reported in 23 | [rakudo repository](https://github.com/rakudo/rakudo/issues). 24 | 25 | If someone opens an issue that doesn't belong in Problem Solving, 26 | then anyone with sufficient GitHub permissions to do so should close 27 | the issue and either direct the user to the correct place to address 28 | this issue (e.g., the Rakudo repo) or open an issue themselves. 29 | 30 | ### Step 2: Initial proposed solution 31 | 32 | Anyone (including the person who opened the issue) can 33 | submit an initial proposal as a comment in reply to the issue. 34 | 35 | To do so, start a comment with “Initial proposal:” and provide a short and 36 | clear description of the solution you're suggesting. Include just enough 37 | details to paint the general picture and refrain from writing too much 38 | (which will be required for the next step, but not now). 39 | 40 | Good solutions may resolve more than one problem: if so, link all other 41 | related problems that will be affected by your solution. 42 | 43 | By proposing a solution, you are _typically_ volunteering to implement 44 | that solution. If you know that you won't be able to work on a 45 | full solution, please **say so when proposing that solution**. Having a 46 | hero who will carry a solution though to implementation is often 47 | essential, but it is also important to hear out good heroless ideas. 48 | 49 | ### Step 3: Discussion of the proposal 50 | 51 | After the initial proposal, everyone is encouraged to discuss the idea and point 52 | out any flaws, implementation details, suggested changes, etc. that 53 | they might see. (Of course, both before and during step 3, people 54 | can discuss the problem generally rather than a particular solution.) 55 | 56 | In step 3, anyone can comment, but two people have an especially 57 | important role to play: the person who wrote the original proposal 58 | and the _assignee_ for the issue. 59 | 60 | #### Assignees 61 | 62 | Issues are assigned to corresponding devs (see 63 | [the list](#labels-and-responsible-devs)). The assignee's job is 64 | to help drive the process, provide vision, and assist everyone 65 | involved. Assignees can provide feedback, ask for clarifications, 66 | suggest changes and so on as they see fit. 67 | 68 | Assignees can provide feedback on an initial solution, provide guidance 69 | about what the full solution should include (e.g. what should be 70 | covered in the document, additional requirements, etc). They can also 71 | reject initial proposals at step 3 (though this shouldn't happen often). 72 | 73 | If an assignee is pleased with the initial proposal, they can ask to 74 | submit a fullblown solution. Alternatively, if the person who suggested 75 | the solution feels they have received enough feedback, they can decide to 76 | submit a full solution. Either way, submitting a solution moves us to the 77 | next step. 78 | 79 | 80 | ### Step 4: Submitting a full solution 81 | 82 | After a problem/solution has been discussed sufficiently, someone should 83 | submit a Pull Request with a detailed proposal that would solve the problem. 84 | This PR should add a document to the "solutions" directory in this repo. 85 | Typically, the solution will come after a user has officially proposed an 86 | initial solution (as described in Step 2, above) and, typically, the PR would 87 | be written by the same user who wrote that initial solution. 88 | 89 | However, neither of these part of the above is _absolutely_ required. For 90 | example, if someone writes an initial solution but doesn't have time (or no 91 | longer has time) to work on implementing the solution, it's fine for someone 92 | who does have time to submit the PR. Similarly, if an initial solution has 93 | been discussed without anyone _formally_ writing an "initial solution" comment, 94 | someone who was involved in that discussion can step forward and draft a PR. 95 | (This can sometimes happen when one user has a partial solution and other 96 | users add to it without anyone drafting a formal initial solution.) That said, 97 | it's still better to have a written initial solution and for the PR to be written 98 | by the same person. 99 | 100 | The PR should act as a documentation for the solution and should provide 101 | all details that are required to implement the solution. Keep your document 102 | consistent with other files in the solutions directory (naming, directory 103 | structure, markup and so on). 104 | 105 | At this point, anyone can provide feedback on the full solution and, if 106 | desired, the PR author can revise the PR based on that feedback. 107 | 108 | 109 | ### Step 5: Solution resolution 110 | 111 | Once someone has submitted a PR, it can be resolved in one of 4 ways: 112 | 113 | 1. Consensus acceptance 114 | 2. Speedy acceptance 115 | 3. Acceptance without consensus 116 | 4. Non-acceptance 117 | 118 | #### Consensus acceptance 119 | 120 | The most common way for a proposal to be accepted is for the discussion to 121 | proceed to a point where a consensus exists in favor of the solution. A 122 | consensus does not require _unanimity_, but it should be clear that the 123 | Raku community as a whole supports the solution. In particular, if 14 days 124 | pass between the time when the PR (or the latest revision of the PR, if it's 125 | edited) was proposed and none of the [reviewers](#reviewers) (listed below) 126 | have objected, then the proposer of the PR can use their judgement to determine 127 | whether consensus exists. However, if any of the reviewers objects to the PR's 128 | solution or 14 days have not yet passed, then consensus does *not* support 129 | that solution. 130 | 131 | #### Speedy acceptance 132 | 133 | If all reviewers approve a solution, then it can be accepted even if 14 days 134 | have not passed. 135 | 136 | #### Acceptance without consensus 137 | 138 | In **very** rare cases, a PR's solution can be accepted even when the Raku 139 | community cannot reach consensus. When the Problem Solving process was first 140 | adopted, the way Raku solved problems when consensus couldn't be reached was by 141 | an action by the Benevolent Dictator for Life (Larry Wall). After the [Raku 142 | Steering Council Code](https://github.com/Raku/Raku-Steering-Council/blob/main/papers/Raku_Steering_Council_Code.md) 143 | was adopted, the process for resolving deadlock shifted to the RSC as 144 | described in that document. In either case, this power should be exercised 145 | only as a last resort and in extremely exceptional cases. 146 | 147 | #### Non-acceptance 148 | 149 | If a solution is not accepted by any of the methods described above, then 150 | it is not accepted. Arguably, this isn't a resolution at all – the problem 151 | remains unsolved and the issue stays open. But that particular solution 152 | has failed to gain acceptance (though, of course, a different solution or 153 | even a revised version of the same solution could later be accepted). 154 | 155 | 156 | ## Edge cases and other notes 157 | 158 | * If any of the merged solutions needs an adjustment, the process should 159 | start from the beginning. That is, an issue should be filed stating 160 | the problem with the current solution, and the process continues as 161 | normal. PRs are allowed to change, modify and shadow existing 162 | solutions. 163 | * Assignees are allowed to call for a “shortcut” to any problem, in 164 | which case the solution is applied directly without going through 165 | the whole process. 166 | * Non-functional changes to existing solutions automatically go 167 | through a shortcut (typos, grammar, formatting, etc.), just submit 168 | a PR right away. 169 | * If a shortcut receives any criticism from the corresponding 170 | development team or other affected parties, it can be reverted and 171 | the full formal process should begin. 172 | * Passing the assignee status is allowed provided that the receiving 173 | party agrees. One-time assignees are allowed through this process. 174 | * People are allowed to be assigned to their own PRs. 175 | 176 | 177 | 178 | ## Labels and responsible devs 179 | 180 | File a `meta` issue if you want to create a new label or if you want 181 | to be added as a responsible dev. 182 | 183 | * `meta` – changes to the `problem-solving` repo and this document 184 | * [@codesections](https://github.com/codesections) 185 | * `language` – changes to the [Raku language](https://github.com/perl6/roast/) 186 | * – 187 | * `rakudo` – big changes to [Rakudo](https://github.com/rakudo/rakudo/) 188 | * – 189 | * `moarvm` – big changes to [MoarVM](https://github.com/MoarVM/MoarVM) 190 | * – 191 | * `documentation` – big changes to 192 | [Raku documentation](https://github.com/Raku/doc/) and other learning 193 | resources 194 | * [@coke](https://github.com/coke) 195 | * `unicode` – Unicode and encoding/decoding 196 | * [@samcv](https://github.com/samcv) 197 | * `infrastructure` - servers, hosting, cloud, monitoring, backup and automation 198 | * [@rba](https://github.com/rba) 199 | * [@maettu](https://github.com/maettu) 200 | * `fallback` – if no other label fits 201 | * [@codesections](https://github.com/codesections) 202 | 203 | ## Reviewers 204 | 205 | File a `meta` issue if you want to be added to this list. 206 | 207 | * [@codesections](https://github.com/codesections) 208 | * [@FCO](https://github.com/FCO) 209 | * [@JJ](https://github.com/JJ) 210 | * [@lizmat](https://github.com/lizmat/) 211 | * [@maettu](https://github.com/maettu) 212 | * [@masak](https://github.com/masak) 213 | * [@MasterDuke17](https://github.com/MasterDuke17) 214 | * [@rba](https://github.com/rba) 215 | * [@samcv](https://github.com/samcv) 216 | * [@timo](https://github.com/timo) 217 | * [@tony-o](https://github.com/tony-o) 218 | * [@vrurg](https://github.com/vrurg) 219 | -------------------------------------------------------------------------------- /solutions/documentation/front-matter-for-routines.md: -------------------------------------------------------------------------------- 1 | # Front matter for routine pages 2 | 3 | The [documentation for Raku](https://docs.raku.org) is generated from 4 | the [source](https://github.com/Raku/doc) by processing the primary 5 | content (in pod6 format), and generating secondary content that will 6 | depend on the type of the page. As a matter of fact, there are two 7 | rough kind of pages: 8 | 9 | * Tutorial pages, which are free format, but can be indexed. 10 | * Class pages, which have a more or less fixed format, are indexed. 11 | 12 | Several types of secondary pages are generated from that, but we'll 13 | focus on *routine* pages. These pages are extracted from those two 14 | kind of pages, but other than that they don't have any kind of 15 | additional content other than the routines (and methods) in 16 | lexicographical order of the classes they are declared for. 17 | 18 | This also provokes a series of hacks, needed to index and generate 19 | pages for independent routines, as well as operators, which are 20 | actually routines too. But the bigger problem is that there's no 21 | tutorial-style content for routines, forcing the user to hopscotch 22 | around from one definition to the next to find the real semantics. 23 | 24 | Since the Big Summer Split, documentation and its rendering is 25 | decoupled, with documentation (and some stuff that will be eventually 26 | split) in the Raku/doc repo, and Documentable, which is the API, in 27 | the Raku/Documentable repo. I propose to follow these steps to be able 28 | to index and document routines separately: 29 | 30 | 1. Almost inmediately, we can change the sorting order of the 31 | routines/methods in the current pages from lexicographical on the 32 | class/Role name they're defined to "hierarchical" order, with 33 | routines lower in the hierarchy first. This will help somehow by 34 | focusing on improving those versions of the routine, while the rest 35 | of the solution is worked out. 36 | 1. Add a new `kind` "Routine" to Documentable 37 | (see 38 | [documentation](https://raw.githubusercontent.com/Raku/Documentable/master/docs/Language/document-format.pod6) for 39 | this. 40 | 2. Process that routine in such a way that it has an introduction 41 | (like Types right now) + collation of all routines and methods with 42 | the same name. 43 | 3. Ensure this works for operators too. 44 | 4. Ensure that current URLs are maintained. 45 | 4. Write boilerplate for routines that will not have independent 46 | documentation, so that it defaults to what we have now. Make it reasonable. 47 | 4. Split 48 | the 49 | [page for independent routines](https://docs.raku.org/language/independent-routines) in 50 | as many pages for routines to seed the documentation. 51 | 52 | -------------------------------------------------------------------------------- /solutions/documentation/search-categories.md: -------------------------------------------------------------------------------- 1 | # Search categories 2 | 3 | The Pod6 markup language provides a mechanism to "index" text via the `X` formatting code. 4 | The code consists of the optional text part that is formatted into the document if given 5 | and a number of obligatory, possibly multi-level (separated with a comma), 6 | index entries separated with a semicolon: 7 | 8 | ``` 9 | # Common 10 | X 11 | # Variations 12 | X<|entry-level-1, entry-level-2> 13 | X<|entry1;entry-level1, entry-level2;entry2> 14 | ``` 15 | 16 | The [documentation for Raku](https://docs.raku.org) website supports a search feature: 17 | the user can look up terms by text to navigate to relevant documentation pieces describing 18 | the term. 19 | 20 | On the website the search results (a set of search entries) are presented 21 | as a list of items divided into *categories*. 22 | 23 | Both forming a set of the search entries for the website and assigning 24 | categories to entries is based upon the Documentable module code which 25 | extracts the search anchors from the index entries, headings and pages. 26 | 27 | At the time Documentable module was written, a lot of legacy code 28 | was simply migrated into the module and as a result the existing 29 | system for the indexing remains to be unpredictable and bizarre 30 | to the documentation writer. 31 | 32 | Currently, in Documentable there are 6 (six) different code paths where the 33 | category is set for different cases of index entries, headings and pages, 34 | and each has its own arbitrary way of deciding the category. 35 | 36 | More so, in the past, as the documentation emerged with no guidelines 37 | for indexing entries at all, people had to come up with index formatting 38 | in an ad-hoc manner, sometimes confusing its syntax in different ways 39 | and as the result the state of indexed entries and usability of the search suffers. 40 | 41 | This document describes a solution chosen for the Raku language 42 | documentation sources to solve its specific range of issues in this 43 | particular field and may or may not apply to other usages of Pod6. 44 | 45 | # Currently existing ways to categorize search entries 46 | 47 | Current Raku documentation organization layout consists of six types of pages, 48 | these include primary pages: 49 | 50 | * Explaining various aspects of the language itself, so assigned kind `Language` 51 | * Describing existing types included in the language, so assigned kind `Type` 52 | * Describing various topics around working with the language, so assigned kind `Program` 53 | 54 | As well as secondary pages, generated based on the primary pages: 55 | 56 | * Explaining routines (subroutines, methods, submethods) provided, so assigned kind `Routine` 57 | * Explaining syntax, so assigned kind `Syntax` 58 | * Describing various concepts the documentation refers to, so assigned kind `Reference` 59 | 60 | To assign a category to a search item, these ways currently exist: 61 | 62 | * For pages of kind `Type`, `Language`, `Program` pages depend on the page subkind 63 | * For secondary, generated documentation pages (kind `Routine`, `Syntax`) try 64 | to guess a category based on a subkind or simply take the first page subkind available 65 | as one 66 | * For entries of kind `Reference` simply take the Kind as a category 67 | * For a Pod6 heading with `X` formatting code inside use the first 68 | entry part as the category (so for `=head1 X 84 | ``` 85 | 86 | Then the `category` term will be indexed under the `entry term` category, 87 | even if the search category `entry term` does not make any sense to the consumer. 88 | 89 | # Solution 90 | 91 | To address the issues described above, I propose to follow these steps: 92 | 93 | 1. Introduce strict guidelines for indexing. 94 | 95 | To specify an index entry, the `X<>` markup code is restricted to be one of the 96 | following forms: 97 | 98 | ``` 99 | X<|$category,term> 100 | X 101 | X 102 | ``` 103 | 104 | where the `$category-1`, ... `$category-N` variables *explicitly* set the category 105 | for the corresponding term indexed and strictly refer to one of the supported 106 | categories described in this document (including possible future extensions), see the next step. 107 | 108 | Sticking to the syntax described here implies two important things: 109 | 110 | * No implicit category setting (setting a category manually becomes mandatory) 111 | * Sub-categories (e.g. `X<|Cat,Sub1,Sub2,Term>`) are forbidden 112 | 113 | Please, do note that in the example above names such as `$category`, `$category-1` are 114 | placeholders for an actual category name. 115 | 116 | Valid examples are: 117 | 118 | ``` 119 | X<|Syntax,does> 120 | X<|Language,\ (container binding)> 121 | X 122 | X<|Variables,$*PID> 123 | X 124 | X 125 | X 126 | ``` 127 | 128 | 2. Establish a list of supported search categories, see Appendix A for the suggested one. 129 | 130 | 3. Write a test for the documentation sources to gather all present index entries 131 | and check them against the approved categories list. The test passes when 132 | all index entries adhere to the approved categories. 133 | 134 | 4. Fix the `Documentable` module indexing bits to make them both clearer 135 | and adhere to the scheme suggested in this document. 136 | 137 | 5. Gradually adapt current documentation index entries to pass both tests. 138 | 139 | 140 | # Outcomes 141 | 142 | * An organized list of categories makes it easier for the user to understand 143 | * A solid state of search categories makes it easier for the contributor to index items into correct 144 | categories 145 | * Possible separate documentation search frontends get a much cleaner set of categories to search by 146 | 147 | # Appendix A: Search Categories 148 | 149 | This list is made with a couple of styling rules in mind, those are: 150 | 151 | * Titlecase over lowercase (`Subroutines` over `routines`) 152 | * Plural over singular (`Subroutines` over `routine`) 153 | * Categorize both Raku language standard library API (`Types`, `Subroutines`) as well 154 | as language-related topics and terms (`Language`, `Syntax`) grouped 155 | 156 | The existing as for 05.01.2021 ad-hoc list of search categories is: 157 | 158 | - [ ] `class` 159 | - [ ] `role` 160 | - [ ] `enum` 161 | - [ ] `module` 162 | - [ ] `Language` 163 | - [ ] `programs` 164 | - [ ] `sub` 165 | - [ ] `prefix` 166 | - [ ] `listop` 167 | - [ ] `infix` 168 | - [ ] `Routine` 169 | - [ ] `postfix` 170 | - [ ] `postcircumfix` 171 | - [ ] `method` 172 | - [ ] `submethod` 173 | - [ ] `routine` 174 | - [ ] `trait` 175 | - [ ] `term` 176 | - [ ] `twigil` 177 | - [ ] `variable` 178 | - [ ] `syntax` 179 | - [ ] `regex` 180 | - [ ] `regex quantifier` 181 | - [ ] `parameter` 182 | - [ ] `quote` 183 | - [ ] `matching adverb` 184 | - [ ] `regex adverb` 185 | - [ ] `substitution adverb` 186 | - [ ] `hyper` 187 | - [ ] `Phasers` 188 | - [ ] `Asynchronous Phasers` 189 | - [ ] `Python` 190 | - [ ] `constant` 191 | - [ ] `hash (Basics)` 192 | - [ ] `rakudoc` 193 | - [ ] `control flow` 194 | - [ ] `:sym<>` 195 | - [ ] `scalar (Basics)` 196 | - [ ] `statement (Basics)` 197 | - [ ] `string literal (Basics)` 198 | - [ ] `TOP` 199 | - [ ] `topic variable (Basics)` 200 | - [ ] `variable interpolation (Basics)` 201 | - [ ] `declarator` 202 | - [ ] `:cached` 203 | - [ ] `eager (statement prefix)` 204 | - [ ] `gather (statement prefix)` 205 | - [ ] `identifier` 206 | - [ ] `classes` 207 | - [ ] `lazy (statement prefix)` 208 | - [ ] `macros` 209 | - [ ] `pack` 210 | - [ ] `react (statement prefix)` 211 | - [ ] `sink (statement prefix)` 212 | - [ ] `supply (statement prefix)` 213 | - [ ] `` 214 | - [ ] `->` 215 | - [ ] `is default (Variable)` 216 | - [ ] `try (statement prefix)` 217 | - [ ] `with orwith without` 218 | - [ ] `Reference` 219 | 220 | Most of them are absorbed during solution's step 3 into the new standard list. 221 | 222 | The standard list is: 223 | 224 | - [ ] `Types` 225 | - [ ] `Modules` 226 | - [ ] `Routines` (a common category for something existing as a method and a subroutine) 227 | - [ ] `Subroutines` 228 | - [ ] `Methods` 229 | 230 | - [ ] `Terms` 231 | - [ ] `Adverbs` 232 | - [ ] `Traits` 233 | - [ ] `Phasers` 234 | - [ ] `Asynchronous Phasers` 235 | - [ ] `Pragmas` 236 | - [ ] `Variables` 237 | 238 | - [ ] `Control flow` (everything related to control flow) 239 | - [ ] `Regexes` (everything related to regex) 240 | 241 | - [ ] `Operators` (a common category for something existing as an operator with different application) 242 | - [ ] `Listop operators` 243 | - [ ] `Infix operators` 244 | - [ ] `Metaoperators` 245 | - [ ] `Postfix operators` 246 | - [ ] `Prefix operators` 247 | - [ ] `Circumfix operators` 248 | - [ ] `Postcircumfix operators` 249 | 250 | - [ ] `Tutorial` 251 | - [ ] `Foreign` (for terms from other languages and migration guides) 252 | - [ ] `Syntax` (legacy, various bits of language syntax explained at meta-level) 253 | - [ ] `Reference` (legacy, default category for general reference) 254 | - [ ] `Language` (legacy, language-related topics) 255 | - [ ] `Programs` (legacy, program writing-related topics) 256 | 257 | # Appendix B: Updates to the list of supported search term categories 258 | 259 | The suggested list of categories is proven to be able to cover all 260 | existing index entries for the existing language documentation at the 261 | time of writing. In case of issues arising, updating it is possible 262 | by starting a discussion with other maintainers and providing the 263 | reasoning behind the change for one of the reasons: 264 | 265 | * The current list does not include an important category which 266 | absolutely does not fit into any of the existing ones 267 | * The current list contains a category hindering the understanding of 268 | the language in any way 269 | * The current list creates cases where name clashing happens. 270 | For example, say the `Asynchronous Phasers` category is not stated 271 | and then both `QUIT` (asynchronous phaser) and `QUIT` ("normal" phaser) 272 | meaning two different things fall into the same category `Phasers` 273 | and result in a confusion 274 | 275 | But not for one of the following reasons: 276 | 277 | * A matter of style or preferences (e.g. `Subroutine` vs `Subroutines` 278 | or `routine`) 279 | * Overspecializing categories (e.g. splitting `Infix operators` into 280 | `Set infix operators`, `Compare infix operators` etc.) 281 | -------------------------------------------------------------------------------- /solutions/language/Add-head-skip-tail-subs.md: -------------------------------------------------------------------------------- 1 | This is a solution to https://github.com/Raku/problem-solving/issues/328 . 2 | 3 | Merge Pull Request https://github.com/rakudo/rakudo/pull/4973 and add 4 | appropriate tests to roast. 5 | -------------------------------------------------------------------------------- /solutions/language/Path-to-Raku.md: -------------------------------------------------------------------------------- 1 | # The Path to Raku 2 | 3 | This document describes the steps to be taken to effectuate a rename of 4 | `Perl 6` to `Raku`, as described in issue #81. It does not pretend to be 5 | complete in scope or in time. To change a name of a project that has been 6 | running for 19+ years will take time, a lot of effort and a lot of 7 | cooperation. It will affect people in foreseen and unforeseen ways. 8 | 9 | ## Language changes 10 | 11 | ### `.perl` 12 | 13 | The `.perl` method should be deprecated in 6.f, and removed in 6.g. It 14 | should be replaced by a `.raku` method, which will be specified in 6.e 15 | (Rakudo can provide for it as soon as implemented). This could be 16 | implemented by a global search/replace of `.perl` to `.raku` (both in 17 | method names and in calls) in `src/core`, `src/Perl6` and `lib`. A new 18 | `Mu.perl` method should be added that will later come to issue a 19 | DEPRECATED message, and then delegate to `.raku`. 20 | 21 | To retain compatibility with modules that declare a method `perl`, the 22 | default `raku` method should check if the type in question has a 23 | non-default `perl` method (that is, not the one from `Mu`) and, if so, 24 | call it. Once `.perl` is deprecated, it should issue the deprecation 25 | warning also. 26 | 27 | Renaming to `.code` currently clashes with `CallFrame.code`, visually clashes 28 | with the `.codes` method, and it being a generic name, probably also clashes 29 | with modules and other code that exists in the wild. 30 | 31 | ### `$*PERL` and `Perl` 32 | 33 | `$*RAKU` and the `Raku` class will be the replacement of `$*PERL` and the 34 | `Perl` class, which initially will just be aliases. At a language boundary 35 | switch, they will become actual type declarations. 36 | 37 | ### `PERL6LIB` 38 | 39 | A `RAKULIB` environment variable will be introduced into a Rakudo release, 40 | and specified as part of 6.e. If found in the environment, it will be used in 41 | favor of `PERL6LIB`. From 6.f, use of `PERL6LIB` will issue a deprecation 42 | warning. 43 | 44 | ### `PERL6_HOME` 45 | 46 | This was only very recently introduced, and is likely not in wide use yet. 47 | We could consider immediately replacing it with `RAKUDO_HOME` in an upcoming 48 | Rakudo release, perhaps with a short-term fallback/warning - or error - if 49 | it's missing, but `PERL6_HOME` is found. 50 | 51 | ### Pragmas 52 | 53 | The `use isms ` should **NOT** be changed to `use isms `. 54 | Similarly `use Foo:from` and the `:lang` parameter to `EVAL` should 55 | not be changed as to allow more flexibility should the Perl 5 community 56 | decide on a name change as well. 57 | 58 | ### Versioning 59 | 60 | Because the next language release (6.e) may not coincide with 61 | the rename, no changes to versioning of the language need to be done. The 62 | next release *will* however be a Raku release, but should be otherwise 63 | completely compatible with previous releases. 64 | 65 | A new *language* version would be the opportunity to make the name change 66 | more widely known with associated marketing efforts. But this will *not* 67 | be with the next (monthlyish) release. 68 | 69 | Given we are no longer forced to have "6" in the version, there are now 70 | more options to do language versioning properly, and this aspect will 71 | need to be discussed separately at a later time. 72 | 73 | ### NQP 74 | 75 | The acronym for NQP is Not Quite Perl. It stays that way, so no changes 76 | to documentation are needed. Generally, the MoarVM / NQP construct should 77 | not matter a lot for the average user. 78 | 79 | ## Documentation changes 80 | 81 | Wherever `Perl 6` is mentioned in the documentation, this should be changed 82 | to `Raku`. A mention of `Perl 6` in the glossary should remain, and maybe 83 | in the documentation of the `.perl` (to be renamed to `.raku`) method. 84 | 85 | A mention to `Perl 6` should only occur when a redirect from `docs.perl6.org` 86 | has been detected / or a special URL to redirect to has been followed (e.g. 87 | https://documentation.raku-lang.org/?from=perl6). 88 | 89 | ## Website changes 90 | 91 | Websites that have `perl6` in their name, should redirect to their 92 | equivalent with a 301 (Moved Permanently). Some way should be devised that 93 | if someone is redirected, that a small explanation of the name change is 94 | offered and that the visitor is indeed at the place they were planning to 95 | be. 96 | 97 | ## IRC Channels 98 | 99 | The IRC channels used by Perl 6 users on freenode (#perl6\*) will need to 100 | be renamed or closed / opened with the new name (#raku\*). New joins should 101 | be forwarded to the new channels. 102 | 103 | Colabti.org will need to be asked to log these channels, so that we can have 104 | backlog again. Unfortunately, it appears to be too difficult to migrate #perl6 105 | logs, so the same approach that was done when the #perl6-dev channel was 106 | created, will need to be followed. So searching the logs will need to be 107 | done on the old names. 108 | 109 | Further down the road, it would probably be a wise idea to make IRC channel 110 | logging one of the infrastructure tasks. 111 | 112 | ## External references 113 | 114 | Many places on the Internet refer to `Perl 6`. These references will need 115 | to be changed to `Raku`, with a small explanation of the name change. This 116 | should be a coordinated effort to avoid duplicity of work, and to make sure 117 | that the explanation of the name change is consistent. 118 | 119 | Many sites, such as Reddit and StackOverflow, use implicit / explicit `perl6` 120 | tags. These will need to be changed or have a `raku` tag added, possibly 121 | with cooperation of the administrators. It should be prevented that "Perl 6" 122 | all of a sudden becomes hard to find on these sites. 123 | 124 | Sites such as PerlMonks appear to be really `Perl` (aka `Perl 5`) focused, 125 | and could possible make that clear in their description, or change their 126 | description to specifically include `Raku`. It would look like the 127 | `/r/perl` Reddit description can be changed to indicate that only `Perl 5` 128 | questions are on topic there. 129 | 130 | ## Technical changes 131 | 132 | All technical changes should make sure that all existing scripts continue 133 | to work without change in the foreseeable future. Additional DEPRECATED 134 | messages will be introduced at point of a 6.e language change. 135 | 136 | ### Executables 137 | 138 | As some packagers have already done, the executable should be called `rakudo`, 139 | since `rakudo` is the name of the implementation. `raku` and `perl6` should 140 | be symlinks. If at all technically possible, running a script using the 141 | `perl6` as the executor should provide a DEPRECATED warning at some point. 142 | 143 | ### Extensions 144 | 145 | The extension `.raku` for scripts, `.rakumod` for modules, and `.rakudoc` 146 | for documentation (POD6) to become the defacto standards for files containing 147 | `Raku` code or documentation. The old `.pm`, `.pm6` and `.pod6` extensions 148 | will continue to be supported for 6.e. In 6.f, the `.pm`, `.pm6` and `.pod6` 149 | extensions could be marked as DEPRECATED, causing a message to be generated 150 | when possible. 151 | 152 | For testing, the extensions `.rakutest` and `.t` should be used, while the 153 | extension `.t6` will continue to be supported for 6.e, with deprecation 154 | messages appearing from 6.f onward. 155 | 156 | Tools and editors should support both `.rakutest` and `.t` extensions. `.t` 157 | extension is shared by other languages, so editors that can interpret 158 | shebangs or have other heuristics should use these means to 159 | disambiguate raku `.t` files from test files written in other 160 | languages. Editors and tools that are raku-oriented (like Comma, zef, 161 | etc.) should assume that `.t` files without a shebang are Raku test 162 | files. 163 | 164 | On Windows, installers should add a `.raku` association alongside the `.p6` 165 | association for the time being. Around the time of 6.f, a `.p6` association 166 | could be deselected by default, and perhaps dropped entirely by 6.g. 167 | 168 | Here are some examples of filenames with new extensions: 169 | * `Set.rakumod` 170 | * `HyperSeq.rakumod` 171 | * `ThreadPoolScheduler.rakumod` 172 | * `ForClass.rakumod` 173 | * `ForClass.rakudoc` 174 | * `01-basic.rakutest` 175 | 176 | Shorter extensions were considered but no good candidates were 177 | found. For example, `.rk*` cannot be used because of their unfortunate 178 | similarity to Racket language file extensions (which uses `.rkt`) and 179 | other direct conflicts with various formats. 180 | 181 | There won't be any additional changes to extensions in the near 182 | future. That is, no alternatives (like shorter variants) will be 183 | supported, and the extensions mentioned in this document are final. 184 | 185 | ### Testing 186 | 187 | Roast continues to be the specification of the language. Only the name 188 | of the language it specifies, changes. Internal references to `Perl 6` 189 | will need to be changed. 190 | 191 | ## Mascot 192 | 193 | Camelia will remain the mascot. The only thing that should change there 194 | is that it is the mascot of `Raku` rather than `Perl 6`. The fact that the 195 | wings contain a "P" and a "6" is obscure enough to not be an issue, and could 196 | be seen as a lasting tribute (easter egg) to the origin of "Raku". 197 | 198 | ## Marketing changes 199 | 200 | Renaming `Perl 6` to `Raku` is an event that should be used to get maximum 201 | marketing result. This will need `Raku` marketing materials. Announcement 202 | should be coordinated, e.g. by a blog post on `opensource.com` or similar 203 | outlets, followed up by links on the various social media outlets, such as 204 | Twitter, Facebook, Hacker News, Reddit, etc. 205 | 206 | Specific attention should be given for the announcement of Raku in non-latin 207 | script countries (such as India, Japan, China, Taiwan) by making sure any 208 | announcements are also translated into appropriate languages for these regions. 209 | Raku, with its more than excellent Unicode support, should be able to make a 210 | big splash for developers in those regions. 211 | 212 | ## Social Media 213 | 214 | Users who want to blog about `Raku` are suggested to always at least mention 215 | `Raku Programming Language` in their blog post or in the boilerplate of their 216 | blogging engine (exactly that string, for better TIOBE rating). Mentioning of 217 | `Perl 6` in such blog posts should only be done if the blog post is actually 218 | about the renaming process or historical matters. 219 | 220 | When using social media that use hash-tags, users are suggested to use the 221 | `#rakulang` hash-tag, and **not** use the `#perl6` hash-tag, unless the 222 | post is actually about the renaming process or historical matters. 223 | 224 | Of course, the same applies to more official social media usage by the core 225 | development team. 226 | 227 | ## Ecosystem changes 228 | 229 | From the standpoint of users, there should not be any change: `zef` should 230 | continue to do what it does. The information about what is in the ecosystem, 231 | is not related to the "perl 6" name at the moment, so does not need any 232 | change either. 233 | 234 | On PAUSE, Perl 6 distributions are automatically uploaded to a "Perl6" 235 | subdirectory, but this is completely transparent to both the author as well 236 | as anything else that needs to look at that as long as a file `META6.json` 237 | exists in the distribution. So for the foreseeable future, no changes will 238 | be needed there. 239 | 240 | Should PAUSE decide to no longer support `Raku` modules in its system, then 241 | alternatives will need to be found and/or implemented. 242 | 243 | ## Effects on modules in ecosystem 244 | 245 | A guide for existing module developers will be provided, which will offer 246 | suggestions of what to do about the rename. If we can generate PRs that's 247 | perhaps also helpful, though we might want that to be opt-in: authors with 248 | a load of modules might be unpleasantly surprised to wake up one morning 249 | to an inbox full of PRs. 250 | 251 | Such a guide should help authors with modules that either mention "perl6" 252 | or "p6" in their repo name, or mention "Perl 6" in their documentation. 253 | 254 | A proposed draft of such a guide is included at the end of this document. 255 | 256 | ## Effects on running sub-projects 257 | 258 | Projects, such as Comma and Cro do not need any notifications, but other 259 | sub-projects may need to get advance notice. An inventory of these 260 | sub-projects will need to be made, and their maintainers be notified 261 | individually, rather than through social media. This is both to stress 262 | the urgency for a change, and to be able to present a "clean slate" to the 263 | general public when announcements about the name change *are* made through 264 | social media. 265 | 266 | ## Effects on books 267 | 268 | Currently printed copies of books will probably need a sticker like "Covers 269 | the new exciting Raku programming language". 270 | 271 | Perl 6 books that have been open sourced, can be adapted by the community or 272 | the original author: a "Migration Guide for Book Authors" should help authors 273 | with this. Since ebook sales currently outperform printed books by an order 274 | of magnitude, preparing another version of an ebook should be a relatively 275 | small effort, which can actually be distributed among many individuals using 276 | modern source control techniques. 277 | 278 | ## Effects on the Perl community 279 | 280 | There is a (small) part of the Perl community that welcome the rename, as they 281 | don't want anything to do with the language and are glad to disassociate it 282 | from the Perl name. There are community members with an active interest in 283 | both Perl 5 and Raku, and some of those who only do one or the other still 284 | feel there is much to be learned from, and shared with, each other, especially 285 | given the many shared design values of the languages. 286 | 287 | The name change of `Perl 6` to `Raku` is also intended to have a healing 288 | effect on a community that has been effectively split for many years. 289 | It is the hope of the Raku core development team that future events will 290 | continue to cater for both `Perl` as well as `Raku` presentations. 291 | 292 | ## Effects on user groups 293 | 294 | Each Perl user group (Perl Monger group) will have to decide for themselves 295 | what they want to do with this new situation. More active groups in the 296 | past years, have started using the services of online meeting organizers 297 | such as MeetUp. To indicate the changed situation, it may be a good idea 298 | to change the names of such groups, e.g. from "Foo Perl Mongers Meeting" to 299 | "Foo Perl Family Meetup" or "Foo Perl Community Meetup". Should a user 300 | group decide to only focus on `Perl 5` or `Raku` only, then they are of 301 | course open to not change their name, or to change it to something like 302 | "Foo Raku Meetup". This could coincide with the official announcement, 303 | and maybe special events to celebrate the name change. 304 | 305 | ## Effects on events 306 | 307 | Event organizers are, as always, completely free in the naming of their events. 308 | If an event would like to cater for both `Perl` and `Raku` attendees, then 309 | this should be reflected in the name of the event. An event with just `Raku` 310 | in its name, would appear to cater only for attendees interested in `Raku`. 311 | An event with just `Perl` in its name, would appear to cater for attendees 312 | interested in `Perl 5` only. Suggestions for naming events are (where "Foo" 313 | is a place / country name): 314 | 315 | The Foo Perl Community Workshop 316 | The Foo Perl Family Workshop 317 | The Foo Perl and Friends Workshop 318 | The Foo Perl and Raku Conference 319 | The Foo Raku and Friends Workshop 320 | 321 | etc. etc. 322 | 323 | ## Relationship with The Perl Foundation 324 | 325 | No changes should be necessary with regards to the relationship with The 326 | Perl Foundation. But this is mostly up to The Perl Foundation. A suggestion 327 | would be to make the website of The Perl Foundation more general: a Perl 328 | Family. With equal attention for Perl, Raku, RPerl and CPerl, and emphasis 329 | on continued development on all projects. 330 | 331 | Should The Perl Foundation decide to not want to have anything to do with 332 | `Raku`, only then should an alternate organisational support be discussed. 333 | 334 | However, since "Yet Another Society" is doing business as "The Perl 335 | Foundation", maybe it is an idea to create another "doing business as" 336 | called "The Raku Foundation". Which would make it clear that "The Perl 337 | Foundation" is for Perl 5 only, whereas "The Raku Foundation" would be for 338 | Raku only. While both are part of the Perl Mindset in the "Yet Another 339 | Society". 340 | 341 | ## Draft guide for module developers 342 | 343 | The Raku team are grateful to all those who have developed modules for the 344 | language. We recognize that most contributors are doing so on a volunteer 345 | basis, and that this work is often done in one's (lack of) free time. 346 | 347 | This guide provides some suggestions on how module authors can handle the 348 | Perl 6 to Raku renaming. While there is a suggested timeline here, it is 349 | to be interpreted as "at your convenience", rather than an expectation to 350 | do these things quickly. 351 | 352 | ### In the period immediately after the rename is agreed... 353 | 354 | You might consider: 355 | 356 | * Mentioning Raku in your module's README or other documentation. It's up to 357 | you if you wish to have something like "Raku (formerly Perl 6)", to stay 358 | findable for such searches for some time, or to simply adopt the Raku name 359 | right away. 360 | * Renaming the GitHub repository if it contains `p6` or `perl6` (remember to 361 | update the `sources` entry in `META6.json` if doing this). 362 | 363 | In this interest of your module continuing to work with existing Rakudo 364 | installations, please *do not*, at this point: 365 | 366 | * Change module file extensions away from `.pm6` 367 | * Rely on `.raku`, `Raku`, `$*RAKU`, and similar 368 | 369 | ### Around the release of 6.e... 370 | 371 | This is expected to happen in 2020. At this point, you might consider: 372 | 373 | * Changing module file extensions (remembering to update `META6.json`) 374 | * Switching to use `.raku`, `Raku`, `$*RAKU`, and similar in the module's 375 | code (most modules will not be doing this anyway) 376 | * Dropping remaining mentions of Perl 6 in the documentation, unless it is 377 | there for historical interest 378 | -------------------------------------------------------------------------------- /solutions/language/SWOT-to-Raku.md: -------------------------------------------------------------------------------- 1 | # SWOT analysis of renaming Perl 6 to Raku 2 | 3 | ## Strengths 4 | 5 | - removes the confusion that Perl 6 is Perl version 6 (a new version of Perl). 6 | - frees up higher versioning of "Perl" 7 | - no longer linked to bad reputation of "Perl" 8 | - removes source of Perl community stress 9 | - is a cool name that should appeal to younger people 10 | - name should better appeal to non-english native speakers 11 | - should be easier to get distinctive TIOBE rating 12 | 13 | ## Weaknesses 14 | 15 | - will *still* be linked to "Perl" because of historical connection 16 | - Perl 6 books will not know of name change, and thus continue to "squat" 17 | - Perl 6 blog posts will not know of name change, and thus continue to "squat" 18 | - no longer linked to good reputation of "Perl" 19 | - may be hard to find using search engines, at least initially 20 | - must start with TIOBE rating from scratch 21 | - in social media, #raku as a tag is overloaded with Japanese pottery meaning 22 | 23 | ## Opportunities 24 | 25 | - could be considered a brand new language, and thus more interesting to some 26 | - should re-invigorate development 27 | - should re-invigorate marketing 28 | - with better branding, should be able to get easier sponsorships / grants 29 | - may get core developers who have left, back into the core team 30 | - could be marketed as a programming language without corporate backing, and thus free from corporate influencing / agenda 31 | - could be marketed on its own, with its own strengths, such as multi-paradigmity and concurrency, as well as coverage of the Unicode standard 32 | - could be marketed as the 100-year language properly 33 | - current Perl 6 books could be updated while changing the name 34 | - current Perl 6 blog posts could be better marked with TIOBE tag (as they presently are not tagged correctly in general) 35 | - reworked documentation could have *all* pages properly TIOBE tagged 36 | - in social media, use new, distinctive #rakulang tag 37 | 38 | ## Threats 39 | 40 | - may lose current users 41 | - may lose current core developers 42 | - may lose current book writers 43 | - may lose support from local Perl user groups (PerlMongers) 44 | - may lose support of organizations such as The Perl Foundation, EPO, YEF 45 | - may be made fun of as the language that cannot make up its mind 46 | - may cause incompatibities / breakage that will reflect badly on overall image 47 | - could drain critical mass from Perl 5 events 48 | - could drain critical mass from Raku events 49 | - may not get enough traction to grow anyway 50 | -------------------------------------------------------------------------------- /solutions/language/Windows-process-argument-quoting.md: -------------------------------------------------------------------------------- 1 | Windows process argument quoting 2 | ================================ 3 | 4 | Windows does not have the concept of an ARGV array. At the API level ([CreateProcess()](https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw)) there is only one single string that is passed. There is a [convention](https://docs.microsoft.com/en-us/previous-versions/17w5ykft(v=vs.85)) ([CommandLineToArgv()](https://docs.microsoft.com/en-us/windows/desktop/api/shellapi/nf-shellapi-commandlinetoargvw) implements that) of how a string array is serialized to a single string and back. With rare exceptions all programs adhere to this convention. The most prominent exception is `cmd.exe`. `cmd.exe` just directly processes its argument string as if you'd have pasted it into a cmd.exe window. When calling a `.bat` file, Windows implicitly wraps the call in `cmd.exe /C `. (The exact command Windows actually puts around the command is currently unknown.) Thus calling any `.bat` file is subject to `cmd.exe` processing. 5 | 6 | So in most cases arguments need to be serialized using the Microsoft convention. In some cases, usually when dealing with `.bat` files, one needs to serialize the arguments differently though. 7 | 8 | All APIs in Raku to call processes do always quote arguments using the Microsoft convention and provide no escape hatch to disable the quoting. So it's impossible to call processes with a different serialization format. 9 | 10 | A good solution should: 11 | 12 | - Work in the common case without the user having to know about any of this 13 | - Give enough control to the user to call any program the way he wants 14 | - Make sure the changes don't make the API more complex for the use cases not affected by this 15 | 16 | 17 | Solution 18 | -------- 19 | 20 | `sub run()`, `Proc.Spawn()` and `Proc::Async.new()` are extended with a new argument `:$win-verbatim-args` defaulting to `False`. If the argument is left off or set to `False`, the arguments are quoted according to the Microsoft convention. This is identical to Rakus previous behavior and thus backwards compatible. 21 | 22 | When passing `True` the passed arguments are concatenated with a single space. No other processing takes place. This allows to manually quote the arguments as necessary. 23 | 24 | Other serialization strategies can be implemented in ecosystem modules. 25 | 26 | The name `win-verbatim-args` is named similar to a matching flag in `libuv` and `node.js`. This increases the recognition factor. 27 | 28 | 29 | Implementation in Rakudo 30 | ------------------------ 31 | 32 | The serialization of the arguments happens in Rakudo. Backends are expected to not touch the single arument string they receive from Rakudo on Windows in any way. 33 | 34 | The JVM does not provide any mechanism to disable or influence the argument quoting in any way. It does however implement a sophisticated heuristic to guess which quoting the user might want and acts accordingly. So on the JVM backend the above described flag is ignored and arguments are passed as separate strings to the JVM backend. 35 | 36 | 37 | Further reading 38 | --------------- 39 | 40 | - The problem-solving ticket: [Raku/problem-solving#20](https://github.com/Raku/problem-solving/issues/20) 41 | - Older bugreport on this topic: [rakudo/rakudo#2005](https://github.com/rakudo/rakudo/issues/2005) 42 | - Writeup of how commandline processing works on Windows: [Everyone quotes command line arguments the wrong way](https://web.archive.org/web/20190109172835/https://blogs.msdn.microsoft.com/twistylittlepassagesallalike/2011/04/23/everyone-quotes-command-line-arguments-the-wrong-way/). 43 | - Documentation of the Windows API function to parse command line arguments: [CommandLineToArgv()](https://docs.microsoft.com/en-us/windows/desktop/api/shellapi/nf-shellapi-commandlinetoargvw) 44 | 45 | 46 | ### What other languages do 47 | 48 | [libuv](https://github.com/libuv/libuv/blob/c5593b51dc98715f7f32a919301b5801ebf1a8ce/src/win/process.c#L593) quotes arguments compatible to `CommandLineToArgv()`. When passing the `UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS` argument this quoting is disabled and the arguments are just joined with a space. 49 | 50 | [Node.js](https://github.com/nodejs/node/blob/382e859afc7e66600dccfadd4125088444e063c3/lib/child_process.js#L486) exposes a `shell` flag which wraps the call in `cmd.exe /d /s /c ""` by hand and enables `UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS`. 51 | 52 | [Java](https://codewhitesec.blogspot.com/2016/02/java-and-command-line-injections-in-windows.html)s `ProcessBuilder` has a very sophisticated and complex processing of arguments. e.g. it detects whether the user called a `.bat` file or `.cmd` file and acts on that. -------------------------------------------------------------------------------- /solutions/meta/Problem-Solving.md: -------------------------------------------------------------------------------- 1 | # Problem Solving 2 | 3 | See [README.md](/README.md). 4 | -------------------------------------------------------------------------------- /solutions/meta/TheRakuFoundation.md: -------------------------------------------------------------------------------- 1 | This file provides a solution to [issue #263 - The Raku Foundation](https://github.com/Raku/problem-solving/issues/263) by *Andrew Shitov*. The members of the RSC (Raku Steering Council) would like to personally thank *Andrew* for creation of this issue, and the discussions it has brought. 2 | 3 | As outlined in the [Problem Solving Repo](https://github.com/Raku/problem-solving) and the [Raku Governance Code](https://github.com/Raku/Raku-Steering-Council/blob/main/papers/Raku_Steering_Council_Code.md), the Raku Community acts by adopting Problem Solving solutions such as this one, through either consensus or an RSC vote. 4 | 5 | This solution is based on the numerous responses to issue #263, and in particular on [*Dave Rolsky*'s response](https://github.com/Raku/problem-solving/issues/263#issuecomment-782888300), and specifically in that response: 6 | 7 | > Yes, this is true! Filing a DBA will cost us $10 or $25 (I can't remember which) and requires filing one form with the state of Michigan. It also requires us to update our banking info so that the bank accepts checks made out to "The Raku Foundation". I don't think there's much more work required than that. 8 | 9 | Accordingly, the Raku community would like to formally request that Yet Another Society create a "doing-business-as" for YAS under the name "The Raku Foundation". Using the name "The Raku Foundation" has been the plan for [quite some time](https://github.com/Raku/problem-solving/blob/master/solutions/language/Path-to-Raku.md#relationship-with-the-perl-foundation) and has many advantages for both the Perl and Raku communities. Most immediately, it would allow Raku to present a foundation to the world without using a name that requires immediate explanation of the history of Raku and Perl. Longer term, we believe that this move will benefit both language communities by showing that each language is pursuing an independent future. 10 | 11 | ## Status update, September 2021 12 | 13 | Eventually, Yet Another society answered in [September 2nd, 2021 granting the "DBA" (doing business as) The Raku Foundation](https://news.perlfoundation.org/post/raku-foundation-and-tm-update). As of today, October 2nd, 2021, the Raku Foundation is active and will soon have its own website. 14 | -------------------------------------------------------------------------------- /solutions/meta/coc_incident_response_guide.md: -------------------------------------------------------------------------------- 1 | Raku CoC Incident Response Guide 2 | ================================ 3 | 4 | This document describes the Raku Code of Conduct enforcement 5 | procedures in general terms but is not intended to be binding or to 6 | create any rights; in all cases, ensuring that the Raku community is 7 | welcoming, inclusive, safe, and enjoyable for all ("-Ofun") should 8 | take priority over strictly following the procedures described below. 9 | 10 | This guide is not legal advice. 11 | 12 | Before Taking Action 13 | ==================== 14 | 15 | The CoC is enforced by the Raku Community Affairs Team (currently 16 | comprised of the members of the Raku Steering Council). 17 | 18 | When the CAT receives a report of a CoC violation, any members who are 19 | the subject of the report or who have an actual or apparent conflict 20 | of interest shall immediately be recused and will neither participate 21 | in further actions nor access information about the report or the 22 | CAT's response. 23 | 24 | Barring extraordinary circumstances, the CAT will act on all reports 25 | within 72 hours of first receiving the report. The CAT will act by 26 | majority vote and, if practicable, should hold a synchronous meeting 27 | (e.g., a video call) with at least 3 attendees to vote on its action. 28 | However, due to the importance of promptly responding to reports, the 29 | CAT may also act via asynchronous discussion and voting (e.g., over 30 | email). If it does so, it may set a deadline after which failure to 31 | cast an explicit vote will be treated as an abstention. 32 | 33 | Investigating the Incident 34 | -------------------------- 35 | 36 | In some cases (especially those involving in-person conduct), the CAT 37 | may investigate the incident, such as by having one or more members 38 | speak with the reporter, the alleged violator, or others present at 39 | the incident. In other cases (especially those where a violation was 40 | recorded, such as in an IRC log or recorded conference presentation), 41 | no such investigation will be necessary. 42 | 43 | When considering alleged violations, the CAT should bear in mind that it 44 | lacks the resources of the formal legal system and that the actions it 45 | takes inflict far less harm than those taken by the legal system. 46 | Accordingly, the CAT should not attempt to determine whether a violation 47 | has been proven beyond a reasonable doubt. Instead, it should ask what 48 | action best promotes an -Ofun community based on the facts as they 49 | appear. 50 | 51 | Similarly, the lower severity of the remedies available to the CAT mean 52 | that alleged violators need not receive any of the procedural 53 | protections criminal defendants are entitled to, such as the right to 54 | speak in their defense. Accordingly, it is especially important that 55 | the CAT remember that determining guilt and assigning punishment are 56 | _not_ within its purview; the CAT's only job is to make decisions that 57 | will make the Raku community as -Ofun as possible. 58 | 59 | Additionally, the CAT should remember that the violator's intent 60 | (which may be impossible to accurately determine) is generally not 61 | relevant; instead, the CAT should focus on the impact the incident 62 | had, and the impact that other, similar events could be expected to 63 | have. 64 | 65 | If its investigations into an incident reveal other CoC violations 66 | that were not reported (e.g., an IRC argument in which multiple people 67 | engaged in personal attacks but only one was reported), the CAT should 68 | also evaluate those violations and take appropriate actions. 69 | 70 | Responding to the Incident 71 | ========================== 72 | 73 | After reviewing the incident, the CAT should determine what action to 74 | take in response. When making this determination, the CAT should 75 | consult records of previous violations, both to see whether the violator 76 | has a history of poor behavior and to ensure that similar violations 77 | receive proportional responses. 78 | 79 | Because CoC violations by members of the Raku Steering Council and 80 | others in positions of trust or authority within the Raku community are 81 | especially harmful, these individuals are appropriately held to an even 82 | higher standard than other community members. The CAT should consider 83 | this higher standard when deciding what action to take when someone in 84 | that group has violated the CoC. 85 | 86 | Allowed Responses 87 | ----------------- 88 | 89 | The CAT can respond to reports with any of the following actions or with 90 | any other action it deems appropriate: 91 | 92 | * Determining that the conduct did not violate the CoC or that no action 93 | is needed. 94 | * Determining that the incident requires additional investigation. 95 | * Speaking to the violator informally. 96 | * Editing or redacting media (such as the video of a conference talk) 97 | that contains the violation. 98 | * Removing media that contains the violation. 99 | * Officially warning the violator. 100 | * Temporarily banning the violator from one or more Raku community 101 | spaces. 102 | * Publicly reprimanding the violator. 103 | * Permanently banning the violator from one or more Raku community 104 | spaces. 105 | * Recommending that the Raku Steering Council eject the violator from the 106 | Raku core team. 107 | * Recommending that the Raku Steering Council eject the violator from the 108 | Raku core team and permanently banning them from the Raku community. 109 | 110 | Disallowed Responses 111 | -------------------- 112 | 113 | While the CAT can take appropriate actions other than those listed 114 | above, it should _not_ take any of the following inappropriate actions: 115 | 116 | * Requiring the violator to apologize (voluntary apologies are sometimes 117 | helpful; coerced apologies never are). 118 | * Asking or requiring the target of the violation to decide on or 119 | approve the action (this shifts blame to the target; the decision is 120 | the CAT's responsibility). 121 | * Requiring the violator to avoid the target (this is logistically 122 | unworkable without unfairly burdening the target's privacy and invites 123 | future conflict). 124 | * Assigning someone to "chaperone" or otherwise supervise the violator 125 | (this is unfair and logistically unworkable; if the CAT is concerned 126 | enough about future violations to consider this response, it should 127 | ban the violator instead). 128 | 129 | A Note on Mediation 130 | ------------------- 131 | 132 | The CAT should not require mediation, nor should it recommend mediation 133 | as an action it takes in response to a CoC violation. This is because 134 | violating the CoC is an action that harms the entire Raku community; 135 | reframing the CoC violation as an interpersonal conflict is 136 | inappropriate and suggests that the target of the violation is partly or 137 | equally responsible for the violation. This is incorrect: it is 138 | perfectly possible for two people to dislike each other without either 139 | violating the CoC. 140 | 141 | However, it is equally the case that continued interpersonal conflict or 142 | animosity could lead to future CoC violations and, even if it doesn't, 143 | makes the Raku community less -Ofun. Thus, if the CAT identifies an 144 | underlying interpersonal conflict or cross-cultural misunderstanding, it 145 | can be appropriate for the CAT to offer mediation _after and separate 146 | from_ its resolution of the violation. If the CAT offers mediation, it 147 | should state clearly that mediation is not required and is not a 148 | response that the CAT is taking based on the CoC violation but rather is 149 | a service the CAT is offering to help resolve an underlying 150 | interpersonal or cross-cultural issue. Mediation should _never_ be 151 | offered if the violation is extremely serious (e.g., harassment). 152 | 153 | After Taking Action 154 | =================== 155 | 156 | In all cases, the CAT will inform the reporter how the report was 157 | resolved and may inform others who witnessed the incident. When 158 | deciding whom to inform, the CAT should keep in mind that, if a 159 | bystander is not informed that action was taken based on a CoC 160 | violation, they may conclude that the Raku community permits behavior 161 | of the sort they witnessed. 162 | 163 | The CAT will preserve records of the incident including, at a minimum, 164 | the initial report and a record of any action that was taken (including 165 | informal conversations with the violator). The CAT will ensure that 166 | these records are accessible to the CAT when addressing future reports 167 | but are not accessible to non-members. 168 | 169 | At least annually, the CAT will publish a summary of all reported 170 | incidents and any actions taken in response to those incidents; it may 171 | publish reports (either of multiple actions or a single action) more 172 | frequently based on their number or severity. Except in cases where 173 | naming the violator is essential to the action (e.g., a public 174 | reprimand), the CAT will endeavor not to name violators and will not 175 | name reporters. However, the nature of an incident may make the 176 | identity of one or both parties obvious (for example, if the incident 177 | occurred in a publicly logged IRC channel). 178 | 179 | When summarizing an incident, the CAT should avoid going into more 180 | detail than necessary to fairly inform the community of the incident. 181 | Additionally, the CAT should recall that the identity of any party may 182 | become known even if that party isn't named in the summary, and the CAT 183 | should be especially careful to avoid descriptions of the event that 184 | risk creating misleading impressions of the violation's severity. If 185 | factual disputes about the incident exist, the CAT should avoid creating 186 | the impression of greater certainty about the facts than exists. If a 187 | violator cannot be identified, then the incident summary should state 188 | what action the CAT would have taken if the violator had been 189 | identified. 190 | 191 | The following incident description from the [Conference in the Cloud 192 | 2020 SoC Transparency 193 | Report](https://news.perlfoundation.org/post/cic-2020-soc-transparency-report) 194 | provides an example of the appropriate level of detail: 195 | 196 | > Slides for a talk were reported as containing inappropriate 197 | > material. The CAT reviewed the recording of the talk and agreed that 198 | > this was the case. The CAT talked with the speaker, explaining the 199 | > issue and the consequences. The speaker was given a final warning. 200 | 201 | Whenever the CAT publishes a summary of any incidents or otherwise 202 | communicates publicly, it shall establish an appropriate venue for 203 | discussion (e.g., a GitHub issue) and shall request that all discussion 204 | about the incidents be limited to that venue or sent directly to the CAT 205 | via email. It shall also state that discussion of the incident or 206 | debate about the appropriate response to it is off topic in all other 207 | Raku spaces and may itself be a CoC violation. 208 | 209 | (The reason for this restriction is that defenses of violations can 210 | often do more to make a community non-inclusive than the initial 211 | violation itself, especially when those debates occur in spaces that are 212 | impractical for community members to avoid (such as #raku). It is 213 | essential that there be a space for the community to debate and 214 | criticize the CAT's actions, but it's also essential that this space be 215 | an opt-in one.) 216 | 217 | If community discussion reveals significant confusion or 218 | misunderstanding about a factual issue, the CAT may issue _one_ follow 219 | up communication about the incident. When doing so, it should keep the 220 | following rules (from [How to Respond to Code of Conduct 221 | Reports](https://frameshiftconsulting.com/code-of-conduct-book/)) in 222 | mind: 223 | 224 | * Do not try to persuade people who strongly disagree with you 225 | * Wait to see how people react to the initial announcement 226 | * If necessary, post one follow-up to clarify any genuine 227 | misunderstandings 228 | * Refuse to provide more details about the incident or its handling 229 | * Refuse to engage in one-on-one arguments, online or in person 230 | * Redirect any community-wide discussions into smaller venues 231 | 232 | Regardless of whether the CAT issues a follow-up communication, it must 233 | not edit the original communication in any way, except that it may 234 | optionally add a single clearly labeled edit linking to the follow-up 235 | communication. 236 | 237 | For additional guidance (including guidance on handling more severe 238 | incidents), the CAT may refer to [How to Respond to Code of Conduct 239 | Reports](https://frameshiftconsulting.com/code-of-conduct-book/). If 240 | doing so would be helpful, the CAT may also consult with the Community 241 | Affairs Team or Legal Committee at Yet Another Society or with other 242 | outside advisors. 243 | 244 | 245 | -------------------------------------------------------------------------------- /solutions/meta/code_of_conduct.md: -------------------------------------------------------------------------------- 1 | Raku Code of Conduct 2 | ==================== 3 | 4 | The Raku community is committed to providing a welcoming, inclusive, 5 | safe, and enjoyable environment for everyone. In fact, we have a term 6 | for a "welcoming, inclusive, safe, and enjoyable for all": we say that 7 | the Raku community should be "optimized for fun" – or, in short form, 8 | "-Ofun". Using that terminology, we are committed to ensuring that the 9 | Raku community is -Ofun for everyone, regardless of level of experience, 10 | gender identity and expression, sexual orientation, disability, 11 | neurodiversity, personal appearance, body size, race, ethnicity, age, 12 | religion, nationality, or other similar characteristic. 13 | 14 | Many people have eloquently described the -Ofun community culture to 15 | which we aspire. In the interest of clarity and concision, this 16 | document does not do so; instead, it provides a short, readable list of 17 | unacceptable behaviors so that we're all on the same page about the 18 | ground rules in our particular community. 19 | 20 | The purpose of this CoC is _exclusively_ to ensure that the Raku 21 | community is -Ofun (welcoming, inclusive, safe, and enjoyable for all). 22 | This CoC is not designed to punish wrongdoers, mediate arguments, or 23 | improve the morality of community members. Those goals may be worthy 24 | but are outside the scope of this document. 25 | 26 | Unacceptable Behaviors 27 | ====================== 28 | 29 | The following behaviors, in no particular order, are unacceptable and 30 | violate the Code of Conduct. 31 | 32 | * Using sexist, racist, homophobic, transphobic, ableist, or otherwise 33 | discriminatory language (including repeated/deliberate misgendering or 34 | deadnaming). 35 | * Using insults, profanity targeting a person, personal or political 36 | attacks, or other gratuitously hurtful language (if in doubt, 37 | criticize ideas or behavior instead of people). 38 | * Repeatedly involving someone in a conversation or topic (for example, 39 | by sending them emails or chat notifications) despite their 40 | objection. 41 | * Continuing or repeatedly starting a conversation in an inappropriate 42 | venue (for example, debating the merits of a Code of Conduct violation 43 | in the general #raku IRC channel rather than in the appropriate GitHub 44 | issue or repeated off-topic conversations in #raku-dev). 45 | * Posting or displaying sexually explicit or graphically violent images 46 | or using sexually explicit language or excessive profanity. 47 | * Making inappropriate sexual advances. 48 | * Stalking (online or in person) or inappropriate photography/recording. 49 | * Revealing, or threatening to reveal, someone's contact information or 50 | other non-public data ("doxing") or sharing private content, such as 51 | non-public emails or channel history from unlogged IRC channels, 52 | without consent. 53 | * Any public or private harassment. 54 | * Refusing to agree to follow the existing CoC (arguing that the CoC 55 | should be changed is fine when done in an appropriate venue; refusing 56 | to follow the exiting CoC is not). 57 | * Falsely reporting a CoC violation in bad faith. 58 | 59 | Non Defenses 60 | ============ 61 | 62 | The following "justifications" do _not_ excuse violating the Code of 63 | Conduct: 64 | 65 | * "They started it": When someone violates the CoC, speaking to them 66 | about their behavior or reporting the behavior may be appropriate, 67 | depending on the circumstances. However, no circumstances justify 68 | responding in a way that itself violates the CoC. It is entirely 69 | possible for multiple people in a conversation to violate the CoC; 70 | one person's CoC violations in no way offset the other's. 71 | * "I didn't mean to": Intent may be relevant to determining the 72 | _severity_ of a CoC violation – malicious intent certainly makes 73 | harmful conduct worse. But intent is typically _not_ relevant to 74 | determining whether conduct violates the CoC. Instead, whether 75 | behavior violates the CoC is determined entirely by the impact that 76 | behavior had (and could be reasonably expected to have had). Good 77 | intent does not excuse harmful impact. 78 | * "It's free speech": A huge number of statements are both lawful and 79 | totally unwelcome in the Raku community; speech laws of any 80 | jurisdiction are entirely irrelevant to determining whether particular 81 | conduct violates the CoC. 82 | * "It's just a tone issue": In some communities, ideas are the only 83 | thing that matters – if the substance of an idea is correct, then the 84 | way that idea is expressed is irrelevant. The Raku community is not 85 | like that. In the Raku community, tone matters: forceful criticism of 86 | someone's ideas or behavior can be perfectly in keeping with the CoC 87 | if expressed one way; the same ideas, expressed as a personal attack, 88 | would violate the CoC. 89 | * "That doesn't count because it was on a personal blog": As explained 90 | below, personal blogs, social media profiles, and similar spaces are 91 | _not_ covered by the CoC; however, the Raku community can still respond 92 | to content or behavior in those spaces if that content/behavior makes 93 | complying with the CoC in Raku spaces unlikely or impossible. This is 94 | because enforcing the CoC is never a punitive act; it is always about 95 | ensuring that the Raku community is -Ofun. For instance, the Raku 96 | community would be neither inclusive nor enjoyable if it welcomed 97 | people who post racist screeds to their personal sites, no matter how 98 | assiduously they attempted to separate those statements from their 99 | Raku activities. 100 | * "You'll never prove it": The CoC is not a code of law, and enforcing 101 | it does not require proving that any particular violation definitely 102 | took place (much less proving it by the standards of a criminal 103 | court). All it requires is that the response to an incident help make 104 | the Raku community -Ofun. 105 | 106 | Covered Spaces 107 | ============== 108 | 109 | This CoC applies to the #raku, #raku-dev, and #moarvm IRC channels; the 110 | GitHub repositories under the Raku, Rakudo, and MoarVM organizations; 111 | the perl6/Raku mailing lists; the Raku Discord channel; the r/rakulang 112 | subreddit; posts to Rakudo Weekly News; blogs posted to Planet Raku; and 113 | any other digital spaces Raku may establish. It also applies to all 114 | official Raku conferences and events, physical or digital. 115 | 116 | Modification 117 | ============ 118 | The Raku Steering Council may revise this CoC by majority vote. Any 119 | revisions will have purely prospective effect. 120 | 121 | Enforcement 122 | =========== 123 | 124 | The CoC will be enforced by the Community Affairs Team (excluding any 125 | recused members) as described in the [CoC Incident Response 126 | Guide](./coc_incident_response_guide.md). The CAT will make every 127 | effort to respond within 72 hours of receiving a report; if a violation 128 | occurred, the CAT may respond by a range of actions from informally 129 | discussing the incident with the violator to permanently banning the 130 | violator from Raku community spaces and recommending that the Raku 131 | Steering Council eject them from the core team. Please see the [CoC 132 | Incident Response 133 | Guide](./coc_incident_response_guide.md#allowed-responses) for details. 134 | 135 | Reporting Violations 136 | ==================== 137 | 138 | If you were subject to or witnessed a CoC violation, you should report 139 | it to CAT@raku.org. Alternatively, you can report a violation to any 140 | member of the CAT, who will forward it to all non-recused members of the 141 | CAT. Please be aware that, while the CAT will make all reasonable 142 | efforts not to disclose the identity of individuals who report 143 | violations, it cannot guarantee reporter anonymity nor do reporters have 144 | a way to lessen or otherwise alter the action the CAT takes based on a 145 | report. 146 | 147 | Credits & Sources 148 | ================= 149 | 150 | This CoC draws heavily on the ideas in the book [How to Respond to Code 151 | of Conduct Reports](https://frameshiftconsulting.com/code-of-conduct-book/) and 152 | sources cited in that book (especially [How "Good Intent" Undermines 153 | Diversity and Inclusion](https://thebias.com/2017/09/26/how-good-intent-undermines-diversity-and-inclusion/) 154 | and [No More Rock Stars: How to Stop Abuse in Tech 155 | Communities](https://hypatia.ca/2016/06/21/no-more-rock-stars/)). 156 | 157 | Additionally, this CoC was inspired by/was written with reference to the following codes of 158 | conduct: 159 | [Apache Code of Conduct](https://www.apache.org/foundation/policies/conduct.html), 160 | [Citizen Code of Conduct](https://github.com/stumpsyn/policies/blob/master/citizen_code_of_conduct.md), 161 | [Code for America's Code of Conduct](https://github.com/codeforamerica/codeofconduct/blob/master/code-of-conduct-en.md), 162 | [Conference in the Cloud – Standards of Conduct](https://perlconference.us/tpc-2020-cloud/standards-of-conduct/), 163 | [Conference in the Cloud – Handling Standards of Conduct Incidents](https://perlconference.us/tpc-2020-cloud/handling-standards-of-conduct-incidents/), 164 | [Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct/), 165 | [Django Code of Conduct](https://www.djangoproject.com/conduct/), 166 | [Explorations in RL 2019 Code of Conduct](https://sites.google.com/view/erl-2019/code-of-conduct), 167 | [Geek Feminism Code of Conduct](https://geekfeminismdotorg.wordpress.com/about/code-of-conduct/), 168 | [Geek Feminism Community Anti-Harassment Policy](https://geekfeminism.wikia.org/wiki/Community_anti-harassment/Policy), 169 | [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/), 170 | [Python Community Code of Conduct](https://www.python.org/psf/conduct/), 171 | [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct), 172 | [StackOverflow Code of Conduct](https://stackoverflow.com/conduct), 173 | and 174 | [The Technology Transformation Service Code of Conduct](https://github.com/18F/code-of-conduct/blob/master/code-of-conduct.md). 175 | -------------------------------------------------------------------------------- /solutions/meta/conf.raku.org: -------------------------------------------------------------------------------- 1 | Set the DNS record for "conf.raku.org" to 159.69.82.96, as requested by Andrew Shitov. 2 | -------------------------------------------------------------------------------- /solutions/meta/move-repo-to-raku.md: -------------------------------------------------------------------------------- 1 | Move the private repo of Elizabeth Mattijsen of Raku channel logs to the "raku" organisation. 2 | -------------------------------------------------------------------------------- /solutions/meta/sunsetting-p6c-cpan.md: -------------------------------------------------------------------------------- 1 | # Sunsetting p6c / CPAN ecosystems 2 | 3 | This document provides a solution to [issue 316](https://github.com/Raku/problem-solving/issues/316). 4 | 5 | ## Announcement 6 | 7 | The p6c and CPAN ecosystems are to be deprecated as far as installation of Raku modules is concerned. This will consist of the following steps: 8 | 9 | - Enable the Raku Ecosystem Archive by default in zef immediately 10 | This will allow any installation of a Raku module to look through the [Raku Ecosystem Archive (REA)](https://github.com/raku/REA) if not found on zef, p6c or CPAN ecosystems. 11 | 12 | - Disable the p6c / CPAN ecosystems by default in zef immediately 13 | With the REA enabled, the modules that currently reside on p6c and CPAN ecosystems can be downloaded and installed from the REA. 14 | 15 | - Migrate the remaining raku-community-modules to zef before July 1st 2022 16 | There are about 95 modules in the raku-community-modules repo that still need migrating to zef ecosystem. More than 20 have already been moved. Elizabeth Mattijsen intends to move them all by July 1st, unless someone beats her to it. 17 | 18 | - Alert any module authors after July 1st, 2022 19 | Any module authors still not having moved their modules to the zef ecosystem by July 1st 2022, should be informed with a **single** issue that lists the modules in question. This could be an issue in the problem solving repo, but another repo would work as well. The module authors should also be able to indicate they no longer wish to support a module themselves: in that case, a move to the raku-community-modules repo should be considered. 20 | 21 | - Stop the ecosystem harvesters on January 1st, 2023 22 | Stop running the ecosystem harvesters of p6c and CPAN, both the zef one as well as the one run for the REA. This will effectively disregard any updates of any modules on those ecosystems. This will mark the sunsetting of the p6c and CPAN ecosystems. 23 | 24 | - Offer to move any remaining modules to raku-community-modules 25 | Any authors still having modules in the p6c and CPAN ecosystems, should be offered help in moving their modules to zef and/or the raku-community-modules repo (which would then be followed by a move to the zef ecosystem). 26 | 27 | - Security updates on remaining modules 28 | Any module remaining in the p6c and CPAN ecosystem, should be forked in the raku-community-modules repo and re-released with a version bump if a security update to these, clearly abandoned modules, is necessary. 29 | -------------------------------------------------------------------------------- /solutions/rakudo/Old-Issue-Tracker-Dismantling-Plan.md: -------------------------------------------------------------------------------- 1 | # Old Issue Tracker Dismantling Plan 2 | 3 | [RT](https://rt.perl.org/) was previously used for most of the issue 4 | tracking in the project. Nowadays we use github instead, and RT will 5 | soon become read-only. This document describes the plan for taking 6 | care of the existing RT tickets. 7 | 8 | 1. All existing tickets will be migrated to github using the tools 9 | developed for the similar transition in the Perl project (big thanks 10 | to [@toddr](https://github.com/toddr) and others!). 11 | 12 | + After migration, links to RT tickets will redirect to appropriate 13 | github issues. 14 | 15 | + Majority of open tickets on RT are about Rakudo, and the rest are 16 | related to variety of repos 17 | ([roast](https://github.com/perl6/roast/), 18 | [problem-solving](https://github.com/perl6/problem-solving/), etc.). 19 | 20 | + Due to github limitations it is not possible to move tickets 21 | across organizations, meaning that if we place the repo in `rakudo/` 22 | organization, it will be relatively hard to move tickets to 23 | appropriate repos. 24 | + **Therefore, the repo will be in the `perl6` organization 25 | ([`perl6/old-issue-tracker`](https://github.com/perl6/old-issue-tracker))**. 26 | 27 | 2. At least one 28 | [squashathon](https://github.com/rakudo/rakudo/wiki/Monthly-Bug-Squash-Day) 29 | will be devoted to going through open tickets in the created repo and 30 | moving/closing them as required. Rakudo tickets will be simply marked 31 | with a `rakudo` label and will stay in the same repo. Easy 32 | contribution process (no requirement to sign a CLA) in the `perl6/` 33 | organization means that more people will be able to help. 34 | 35 | 3. After only rakudo tickets are left in the repo, the whole 36 | repository will be transferred to `rakudo/old-issue-tracker`. Links to 37 | RT will keep working either through a double redirect, or the redirect 38 | from RT will be tweaked to point to `rakudo/` organization directly. 39 | 40 | 41 | Note: In this document `perl6/` is used to refer to the github 42 | organization that is currently being used by the Raku project. At the 43 | moment of writing it is `perl6/`, but in the future all repositories 44 | will likely be transferred to `rakulang/` organization (or other 45 | organization with a similar name). The move to a github organization 46 | that embraces the Raku name is a separate effort that will be 47 | discussed elsewhere. 48 | -------------------------------------------------------------------------------- /solutions/rakudo/Use-main-branch.md: -------------------------------------------------------------------------------- 1 | # Switching Rakudo Primary Developement branch to `main` 2 | 3 | Following the decisions mentioned in the following two Raku Steering Council 4 | minutes: 5 | 6 | - [Oct 30, 2021](https://github.com/Raku/Raku-Steering-Council/blob/9ccb0d4554fc7b715ac5ecf4a146ab3fc257025c/minutes/20211030.md?plain=1#L47) 7 | - [Oct 15, 2022](https://github.com/Raku/Raku-Steering-Council/blob/9ccb0d4554fc7b715ac5ecf4a146ab3fc257025c/minutes/20221015.md?plain=1#L5) 8 | 9 | `RakuAST` branch is getting renamed to `main` and that is then used as the 10 | primary developement branch. 11 | 12 | [Rakudo PR #5123](https://github.com/rakudo/rakudo/pull/5123) implements the 13 | principal merging of `master` and `rakuast` branches. 14 | 15 | [This comment](https://github.com/rakudo/rakudo/pull/5123#issuecomment-1345059392) 16 | contains the list of actions necessary to finalize the switch. 17 | 18 | Solves [problem solving ticket #298](https://github.com/Raku/problem-solving/issues/298). 19 | --------------------------------------------------------------------------------