I've started to work on a JavaScript module that will parse Perl POD files. Instead of reinventing the wheel I wanted to take a look at the POD parsing implementations in Perl. I tried to look at some of the POD parsers in Perl, but I mostly saw warnings about strange code.

Ultimately the best would be to have a separate parser that can build a tree from the POD and then tools that can use that tree to create output in some format.

By its name the Pod::Tree modules seemed like a good candidate, but it has not been touched for 5 years. So I thought while I read the code and try to understand if I would like to go in this way, I could also refactor the code and even show the process.

This is the first step.

I got in touch with the author of the module. He told me the module does not have a version control system, but he gave me co-maintainer rights on PAUSE.

The first thing was to download the latest release of this distribution, unzip it, and create a git repository from the source code: 

$ wget https://cpan.metacpan.org/authors/id/S/SW/SWMCD/Pod-Tree-1.17.tar.gz
$ tar xzf Pod-Tree-1.17.tar.gz
$ cd Pod-Tree-1.17/
$ git init
$ git add .
$ git commit -m "import the source of Pod-Tree-1.17 from CPAN"

Then I created a GitHub repository and pushed the code. 

$ git remote add origin git@github.com:szabgab/Pod-Tree.git
$ git push -u origin master

commit

Run the existing tests

Then I wanted to make sure all tests pass: 

$ perl Makefile.PL
$ make
$ make test

This passed, but then when I ran git status I saw it generated lots of new files.

Most of these should probably be in a temporary directory, but before I can make that changes, I'd like to make sure these files won't be added to the Git repository by mistake.

So I created a .gitignore file 

git status > .gitignore

and edited it to make sure the .gitignore file works properly. (I had to remove the header and the footer of the listings and the line about .gitignore itself. I also had to remove the white-spaces in-front of every line.)

commit

Cleaning the .gitignore file

Looking at the new .gitignore file more closely I can see many of the files have .act extension. I started to wonder if all the .act files are generated by the tests.

So first I ran find . -name "*.act" to see if it finds the files. It did.

Then I ran 

$ make realclean

this is supposed to remove all the files created by the make process.

Then I ran find . -name "*.act" again. This time it did not find any file. I ran git status again, just t make sure, no traced file was removed.

I could then edit the .gitignore file, remove all the entries that ended with .act (but left in the html_act entries). Instead of those I just added *.act.

Then to check if this is correct I ran the tests again: 

$ perl Makefile.PL
$ make
$ make test

and checked Git again: 

$ git status

There were no untracked file reported. So *.act indeed covers a large number of the generated files.

commit

Add license and repository link to META files

We have a repository now. The next thing to do is to make sure I can release a new version of the distribution.

It might be strange to some people, but I firmly believe we have to be able to easily release and deploy any software right from the beginning of its development. Once I had a client with a huge internal product written mostly in Perl. Their problem was that they did not know how to easily release a new version and thus they were stuck. When I got to them, the first thing I decided to do was to create a simple way to release and deploy a new version of just a single file. From there I could start to refactor their code-base and include more and more files in the release. Within a few days after I started to work there the first release was out and deployed.

Actually as I understand the whole DevOps movement is some extension of this idea. Bringing the development and the deployment/operations closer to each other.

Anyway, let's get back to Pod::Tree.

As this is a CPAN module the only thing we need to care regarding deployment is to make sure the module is installable with the standard CPAN tools. Luckily it was already that way, so I only have to make sure I don't ruin that.

What remains is the need to be able to package the distribution. This is done using 

$ perl Makefile.PL
$ make
$ make test

followed by 

$ make dist

That worked and it created Pod-Tree-1.17.tar.gz.

That has the same version number as the one on CPAN currently. We need to increase the version number.

For that I've edited the lib/Pod/Tree.pm file and changed $Pod::Tree::VERSION to be '1.17_01'. That's supposed to be a developer version that, when uploaded, will be tested by the CPAN Testers, but will not be the default version to be installed by the regular users.

I've also updated the Changes file and included an entry describing the changes of this release.

Then I ran the release cycle again 

$ perl Makefile.PL
$ make
$ make test
$ make dist

Added Pod-Tree-* to .gitignore and committed the changes

Tagged the current version using 

$ git tag -a 1.17_01 -m 1.17_01

Finally I pushed it out to GitHub: 

$ git push
$ git push --tags

Once that was done, I've uploaded the new zip file to PAUSE and waited for its e-mail.

Normally PAUSE sends 2 e-mails. The first one, confirming the upload, usually arrives a few seconds after the file was uploaded. It contains the md5 checksum of the file. We can use that to verify that PAUSE has received the same file we sent.

The second e-mail, well as I've just learned the second e-mail only arrives if this was not a developer release.

In a nutshell, the second e-mail is the result of PAUSE indexing the distribution, but the whole purpose of developer distributions is to avoid indexing, and thus avoid being the default release to be installed by the CPAN clients. So no indexing, no e-mail. More problematic for me is that I can't know if I get the co-maintainer rights for all the modules in the distribution.

Another release

In order to check the indexing I had to upload a new version, this time with a production version number. For this I've set the version number in lib/Pod/Tree.pm to 1.18. Added an entry to the Changes file, committed the changes, and ran the release cycle again: 

$ perl Makefile.PL
$ make
$ make test
$ make dist

This generated Pod-Tree-1.18.tar.gz which I uploaded to PAUSE.

I got the first e-mail within a few seconds and the second e-mail after 2 minutes. The first one, with a subject line CPAN Upload: S/SZ/SZABGAB/Pod-Tree-1.18.tar.gz confirmed the upload. The second one, with a subject line PAUSE indexer report SZABGAB/Pod-Tree-1.18.tar.gz confirmed that the Status of this distro: OK and Status: Successfully indexed.

TODO

Now that we know we can release a new version and that it will be indexed by PAUSE, we can start working on other changes.

Before that, let's create a /becoming-a-co-maintainer">list of items that need to be done.