@@ -213,15 +213,17 @@ alternatives will need to be found and/or implemented.
213
213
214
214
## Effects on modules in ecosystem
215
215
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
220
220
to an inbox full of PRs.
221
221
222
222
Such a guide should help authors with modules that either mention "perl6"
223
223
or "p6" in their repo name, or mention "Perl 6" in their documentation.
224
224
225
+ A proposed draft of such a guide is included at the end of this document.
226
+
225
227
## Effects on running sub-projects
226
228
227
229
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
306
308
Foundation" is for Perl 5 only, whereas "The Raku Foundation" would be for
307
309
Raku only. While both are part of the Perl Mindset in the "Yet Another
308
310
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