doc
doc copied to clipboard
Raku
Improve module release documentation
Problem or new feature
We need an end-to-end tutorial on what to do to have a module released in the ecosystem, including a very extensive documentation on how to upload, versioning, external dependencies, and so on.
Some parts of the current documentation might be out of date, some other out of place, and some need improvement, like how to use Build.pm, what to do with versions or how to include scripts and resources.
No reference to how and what is checked when incorporated at the ecosystem is done, or if we prefer CPAN or the ecosystem, or if both can be used at the same time...
Suggestions
Revise, improve and revise again. Provide also for ways to check META6.json before release.
FYI, I believe all publicly available modules should be in CPAN only until we get our own equivalent system (being worked on by @tony-o if I remember correctly). The reason is the entries in the "ecosystem" are too fragile and sometimes cause versioning problems.
I also believe we should enforce some minimal standards in order for a module to be shown as "meets standards" for the Raku community. Being able to be installed by zef is a defacto minimum standard, but not what I had in mind. Hard to define, I know, but some "reasonable" test coverage is one thing I expect.
I was thinking about moving my modules to cpan. I haven't done so because I need to get a PAUSE account. There doesn't seem to be any explanation as to what a PAUSE account will give you, and I don't want another subscription to deal with. The ecosystem approach uses git without a problem. Git has the 'release' system, which requires bumping versions. Perhaps that should be a standard?
For a Raku developer, the PAUSE account will give you:
- capability of uploading modules to ecosystem using the CPAN network
- reachability by email with [email protected]
The use of git for the "old" ecosystem works, but afaik predates Github having the concept of releases. In contrast, PAUSE only allows you to upload a distribution with a given version once, ensuring the uniqueness of a distribution given a version.
Using PAUSE currently has the advantage that several channels are made aware of new versions: Twitter and the #raku channel come to mind. Perhaps the 'release' system of Github can be made to do that was well, but then we would be hooked on Github for that, and some people in the community have objections on getting (too) dependent on Github.
At least PAUSE is supported by volunteers and open source. Having said that, I would not mind seeing the 'release' mechanism of Github to also announce itself: it would make my work for the Rakudo Weekly News easier :-)
