Part 2 – Santa Moves from CPAN to Zef with App::Mi6

Prologue

A Christmas ditty sung to the tune of Santa Claus is Coming to Town:

	He’s making a list,
	He’s checking it closely,
	He’s gonna find out who’s Rakuing mostly,
	Santa Claus is Rakuing along.

Santa Claus Operations Update 2, 2021

Santa just heard that Rakoons using best practices are being urged to start putting their modules into the Raku-only module repository called Zef. He wanted to do that soon, since his philosophy is to be a good example of always trying to do the right thing, and helping guide his IT department in the direction of Zef is certainly the right thing to do according to the experts on IRC #raku.

One problem he found, though, was that how to do that with an existing module created by App::Mi6 in its default mode (to generate the new module for CPAN) is not clearly found in one place yet. So, he directed the IT folks to (1) create such a checklist and (2) follow it to put the new SantaClaus::Utils module on Zef.

After a bit of research, Santa’s Rakoons in IT published this checklist:

Install fez, the Zef repository tool

First ensure you have the latest version of Raku (2021.10 as of this writing).

(Note to install with zef or fez you need quotes around module names with adverbs attached as shown in following examples.)

1. Install or upgrade zef to at least version ‘0.13.1’:
   

   $ zef install “zef:ver<0.13.1>“

2. Install or upgrade the Zef repository tool fez to at least version ’31’:
   

   $ zef install “fez:ver<31>“

3. Execute fez with no arguments to see its menu options. Note it has its own Zef installation tools, but we want to use App::Mi6 which will execute them correctly for us.
4. Use fez to get a Zef account (unless you have one already). After a successful effort, the user will find a new file in his or her home directory: .fez-config.json. That file contains the user’s secret key and selected Zef user name (the value of key ‘un’).
5. Install at least version 2.0.1 of App::Mi6:
   

   $ zef upgrade App::Mi6

Convert the module to use Zef instead of CPAN

Change the current working directory to that of the module to be converted.

Then, following the FAQ in the README.md file at https://github.com/skaji/mi6/, complete the following steps:

1. Remove any Raku :auth or :ver ‘adverbs’ from the module name lines in directory ‘lib’. (This step is optional but recommended: any such information in the modules will be compared to that in the ‘META6.json’ file. That information in the ‘META6.json’ file is now required and authoritative to establish those values for a published module, and an exception will be thrown if the module adverbs conflict with the ‘META6.json’ file.)
2. Modify the ‘dist.ini’ file in the module directory to include this line:
   

   [UploadToZef]

3. Recently created modules may have the following line in the ‘dist.ini’ file:
   

   [UploadToCPAN]

If so, remove it or comment it out with a leading semicolon.

1. Optional, but recommended: add a line in the ‘Changes’ file to make the top of it look something like this:
   

   	{{$NEXT}}
   	– Publish to the Raku module Zef repository

2. Ensure the ‘META6.json’ file’s entry for the following key has the correct information:”auth”: “zef:fez-username”,
3. Execute $ mi6 build; mi6 test;
4. Commit changes:
   

   $ git commit -m“now publishing on Zef“

5. Release the module. Following are the expected outputs from a successful release:
   

   	$ mi6 release
   	==> Release distribution to Zef ecosystem
   	There are 13 steps:
   	* Step 1. CheckAuth – Make sure ‘auth‘ in META6.json is ‘zef:xxx‘
   	* Step 2. CheckChanges – Make sure ‘Changes‘ file has the next release description
   	* Step 3. CheckOrigin
   	* Step 4. CheckUntrackedFiles
   	* Step 5. BumpVersion – Bump version for modules (eg: 0.0.1 -> 0.0.2)
   	* Step 6. RegenerateFiles
   	* Step 7. DistTest
   	* Step 8. MakeDist
   	* Step 9. UploadToZef
   	* Step10. RewriteChanges
   	* Step11. GitCommit – Git commit, and push it to remote
   	* Step12. CreateGitTag – Create git tag, and push it to remote
   	* Step13. CleanDist
   	==> Step 1. CheckAuth
   	==> Step 2. CheckChanges
   	==> Step 3. CheckOrigin
   	==> Step 4. CheckUntrackedFiles
   	==> Step 5. BumpVersion
   	Next release version? [0.0.4]:

The dialogue pauses after asking for the desired version. If the version offered is as expected or desired, accept it by merely pressing return, otherwise, enter the desired version number which must be greater than that offered.

Note that in some circumstances, such as attempting a release after a failure, the version number may be incorrect and a manual edit of the "version" value in the ‘META6.json’ file may be required. It may be difficult to identify which program is at fault, but soliciting help on IRC #raku is a good place to start if in doubt.

Continuing after the user response, in this case a bare return only…

	==> Step 6. RegenerateFiles
	==> Step 7. DistTest
	t/01-basic.rakutest .. ok
	All tests successful.
	Files=1, Tests=1, 0 wallclock secs
	Result: PASS
	==> Step 8. MakeDist
	==> Step 9. UploadToZef
	Are you sure you want to upload SantaClaus-Utils-0.0.4.tar.gz to Zef ecosystem? (y/N)

The user can enter ‘y’ to continue or ‘N’ to quit the release process.

Again, after a previous failed attempt the ‘N’ response may be ignored and the user may have to break out of the dialogue with a ctl-C.

Continuing with a ‘y’ response…

	Executing fez —file=SantaClaus-Utils-0.0.4.tar.gz upload
	>>= Looking in “SantaClaus-Utils-0.0.4.tar.gz“ for META6.json
	>>= meta<provides> looks OK
	>>= meta<resources> looks OK
	>>= SantaClaus::Utils:ver<0.0.4>:auth<zef:santa-it-dept> looks OK
	>>= Hey! You did it! Your dist will be indexed shortly.
	It will appear in https://360.zef.pm/
	==> Step10. RewriteChanges
	==> Step11. GitCommit
	==> Step12. CreateGitTag
	* [new tag] 0.0.4 -> 0.0.4
	==> Step13. CleanDist

If there are any problems found by fez or mi6, you should see an error message indicating the problem. You should file an issue with the appropriate program if the error message doesn’t help.

With a normal conclusion, there should be no unrecognized objects in the directory. If there were problems, the clean-up step may not have happened and you may have a GNU *.tar.gz file or an ./sdist directory. They can be safely deleted.

A Christmas Present

The researchers had one more pitch to make: Why go to all this trouble again? Take advantage of the newly-capable mi6 to create a new module to be used by Zef!

The task, create a new module for Santa’s reports:

$ mi6 new —fez Santa::Reports

Note mi6 accepts either --fez or --zef as the same option. Continuing…

	Loading author’s name and email from git config —global user.name / user.email
	Loading zef username from ~/.fez-config.json
	Successfully created Santa-Reports

Voila, a new skeleton module ready for new code, good testing, and publishing on Zef! See the directory listing:

	Santa-Reports/
	dist.ini
	.gitignore
	t/
	01-basic.rakutest
	.github/
	workflows/
	test.yml
	LICENSE
	META6.json
	README.md
	lib/
	Santa/
	Reports.rakumod
	bin/
	Changes

And the important dir.ini file for the Zef repository:

	name = Santa-Reports
	[ReadmeFromPod]
	; enable = false
	filename = lib/Santa/Reports.rakumod
	[UploadToZef]
	[PruneFiles]
	; match = ^ ‘xt/‘
	[Badges]
	provider = github-actions/test

Finally, the fez-critical part of the ‘META6.json’ file:

“auth“: “zef:santa-user“,

Summary

Programs fez and mi6 can now interoperate successfully, thus a user can easily move mi6-created modules to Zef, as well as create new modules for Zef.

Raku module authors are encouraged to move all their modules to Zef for its many features including security and fine-grain differentiation of modules with the same name.

Santa’s Epilogue

Don’t forget the “reason for the season:” ✝

As I always end these jottings, in the words of Charles Dickens’ Tiny Tim, “may God bless Us , Every one!” [1]

Footnotes

1. A Christmas Carol, a short story by Charles Dickens (1812-1870), a well-known and popular Victorian author whose many works include The Pickwick Papers, Oliver Twist, David Copperfield, Bleak House, Great Expectations, and A Tale of Two Cities.