Skip to content

Commit 9310222

Browse files
committed
Add a draft module author guide to the changes
1 parent 7faff8b commit 9310222

File tree

1 file changed

+44
-4
lines changed

1 file changed

+44
-4
lines changed

solutions/language/PATH-TO-RAKU.md

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -213,15 +213,17 @@ alternatives will need to be found and/or implemented.
213213

214214
## Effects on modules in ecosystem
215215

216-
A "migration guide" (perhaps with a better name) for existing developers that
217-
collect suggestions of what to do about the rename. If we can generate PRs
218-
that's perhaps also helpful, though we might want that to be opt-in: authors
219-
with a load of modules might be unpleasantly surprised to wake up one morning
216+
A guide for existing module developers will be provided, which will offer
217+
suggestions of what to do about the rename. If we can generate PRs that's
218+
perhaps also helpful, though we might want that to be opt-in: authors with
219+
a load of modules might be unpleasantly surprised to wake up one morning
220220
to an inbox full of PRs.
221221

222222
Such a guide should help authors with modules that either mention "perl6"
223223
or "p6" in their repo name, or mention "Perl 6" in their documentation.
224224

225+
A proposed draft of such a guide is included at the end of this document.
226+
225227
## Effects on running sub-projects
226228

227229
Projects, such as Comma and Cro do not need any notifications, but other
@@ -306,3 +308,41 @@ called "The Raku Foundation". Which would make it clear that "The Perl
306308
Foundation" is for Perl 5 only, whereas "The Raku Foundation" would be for
307309
Raku only. While both are part of the Perl Mindset in the "Yet Another
308310
Society".
311+
312+
## Draft guide for module developers
313+
314+
The Raku team are grateful to all those who have developed modules for the
315+
language. We recognize that most contributors are doing so on a volunteer
316+
basis, and that this work is often done in one's (lack of) free time.
317+
318+
This guide provides some suggestions on how module authors can handle the
319+
Perl 6 to Raku renaming. While there is a suggested timeline here, it is
320+
to be interpreted as "at your convenience", rather than an expectation to
321+
do these things quickly.
322+
323+
### In the period immediately after the rename is agreed...
324+
325+
You might consider:
326+
327+
* Mentioning Raku in your module's README or other documentation. It's up to
328+
you if you wish to have something like "Raku (formerly Perl 6)", to stay
329+
findable for such searches for some time, or to simply adopt the Raku name
330+
right away.
331+
* Renaming the GitHub repository if it contains `p6` or `perl6` (remember to
332+
update the `sources` entry in `META6.json` if doing this).
333+
334+
In this interest of your module continuing to work with existing Rakudo
335+
installations, please *do not*, at this point:
336+
337+
* Change module file extensions away from `.pm6`
338+
* Rely on `.raku`, `Raku`, `$*RAKU`, and similar
339+
340+
### Around the release of 6.e...
341+
342+
This is expected to happen in 2020. At this point, you might consider:
343+
344+
* Changing module file extensions (remembering to update `META6.json`)
345+
* Switching to use `.raku`, `Raku`, `$*RAKU`, and similar in the module's
346+
code (most modules will not be doing this anyway)
347+
* Dropping remaining mentions of Perl 6 in the documentation, unless it is
348+
there for historical interest

0 commit comments

Comments
 (0)