Aloha Module::Info::File

“Aloha: Means hello and Ehh.. also goodbye” – Bighead

I have just processed some old PRs for Module::Info::File. A Perl distribution I created a long time ago. The module was implemented as a subclass of Module::Info, which I thought lacked some use-cases like basic file handling.

Actually the whole module concept came from a script named version.pl, which extracted basic meta data from Perl packages and Perl module files – this led me to Module::Info and to a solution of subclassing into Module::Info::File.

Anyway I got the PRs processed and got the whole thing working nicely. I had a look at the internals and was not satisfied, parsing version numbers in Perl components have always been interesting.

Based on a old note I had a look at Test::Version a module to test your version strings assuming it did something clever I had not thought of. It appeared that Test::Version was just based on Module::Metadata.

Module::Metadata looks quite impressive so I decided to pull out all the internals of Module::Info::File and implement new logic founded in Module::Metadata – *clickity* *click* – version 1.00 ready and after some testing and adjusting uploaded to PAUSE/CPAN.

The Module::Info::File distribution contains a test to check whether the superclass Module::Info would implement the same functionality, causing Module::Info::File to be obsolete – this just never happened.

Just out of curiosity I read up on Module::Info, which had had several releases, a new maintainer and new functionality, which should have caused the mentioned tests to fail.

I had a look at the documentation and fell over the following:

“Module loaded using new_from_file() won’t have this information in which case you can set it yourself.”

So I thought why not look into whether my code can be ported to the superclass, since I actually do that, I did it prior to 1.00 and I do with 1.00…

Looking around for a Github repository link I ended up in the issues/bug tool RT. Here RT:115147 stood out.

“I wonder if it is time to deprecate Module::Info, or at least point to Module::Metadata as the in-core and preferred mechanism for gathering module information? It looks like Module::Info’s mechanism for parsing $VERSIONs out of files is quite incomplete and outdated.”

I had just changed Module::Info::File to use Module::Metadata and going over the newer releases of Module::Info I located module_info a magnificent tool for replacing my own version.pl – except for the fact that it outputs the filename instead of the package name when providing it with a file as argument.

So now I am unsure of what way to go:

  • Should I deprecate Module::Info::File and just play along with Module::Info and it’s module_info
  • Should I talk to the current maintainer of Module::Info about using Module::Metadata internally so the file handling would improve, since I just observed that worked for Module::Info::File 1.00 and then deprecate Module::Info::File
  • Or should I just forget the whole  Module::Info / Module::Metadata thing and focus or maintaining Module::Info::File

Anyway it is all in the life-cycle of Perl distributions – distributions come and go…

Aloha Module::Info::File

CPAN Pull Request Challenge 2017

I just received a mail from Neil Bowers asking if I would consider having my CPAN distributions be a part of the 2017 CPAN Pull Request Challenge.

My undelayed mental response: Well of course…

I participated in the 2016 Hacktoberfest, I did not contribute much, but I participated and I would have loved to contribute more. These sort of “events” are good, IMHO they bring out the best in open source and they demonstrate the essence of the open source community.

In addition they help tie a community together, so when you are like me; a maintainer of CPAN distributions with very little time, every patch and every PR is most welcome.

A CPAN Pull Request Challenge gives you exactly that.

The CPAN Pull Request Challenge 2017 is soon to kick off, which mean YOU have a chance to benefit from this incredible initiative.

If you have received a mail from Neil respond and be take into consideration for possible PR coming your way or you can tag your issues on Github with the label:

cpan-prc-2017

In order to add the label you have to do the following (This can possibly also be accomplished via the Github API, but that is beyond this blog post):

1. Go to you Github repository issues page
2. Click “Labels”
3. Click “New label”
4. Add the label “cpan-prc-2017”

This mean that the label will be present for both issues and PRs.

Please note that labelling issues will not make them go away automagically, but it will be easier for participants to find issues suitable for the challenge, and also lets participants know that you’re open to a PR for that issue. Since they can be easily identified using a primitive search:

https://github.com/search?q=label%3Acpan-prc-2017&ref=searchresults&utf8=%E2%9C%93

Ask not what you can do for the CPAN Pull Request Challenge 2017, but what CPAN-PRC-2017 can do for you.

This blog post has primarily been on getting help with your distributions and issues from the challenge – there is of course also the option of participating as a contributor of PRs.

Please read more about CPAN Pull Request Challenge at: http://cpan-prc.org/

Have fun – looking forward to your PRs,

jonasbn

CPAN Pull Request Challenge 2017

Public Specifications FTW

Please note that this post is by no means endorsed by my employer, it is a personal reflection on a strategic move I have participated in, in my line of work as a professional software developer.

The above paragraph, which I felt I a need to write as a part of this blog post, is very aligned with the actual post topic in itself, please read on.

The place where I work have for a long time published specifications on some of the offered services. Either this was done using our CMS or using PDF artefacts from a Wordprocessor.

Both processes where tedious and held several issues:

  • Content in CMS
    1. Hard to edit longer documents with figures and cross references
    2. Version control was not obvious
    3. Drafts compared to published documents was not used
  • Wordprocesser artefacts
    1. Version control practically non-existing or external
    2. Document control based on files shares, folders and naming conventions
    3. Manual publication proces

There was probably several other issues I have happily forgotten, like PDF meta-data removal etc.

After having done a lot of open source work in Markdown and on Github and in conjunction with releases of some open source demo clients for our services, I proposed that we published the accompanying public specifications on Github.

This proved to be a very clever move.

It did require some consideration on our side and it was quite a new move to us. Yes we had published specifications for public availability for long a time, but putting these in a public repository was still a new move for us. But the concerns hastily evaporated and the proces became natural and incredibly productive compared to the old processes.

At the time of writing we have 6 open sourced specifications and 3 clients accompanying these and a repository with XSD files supplementing one of the specifications.

Not all of the specifications are finished, but they are out there, so if somebody wants to see what is going on, they are most welcome. We have only received a single pull-request and that is completely okay. We do not want somebody to write our specifications, that is our job, but corrections to sample code, clarifications and of course spelling corrections are most welcome.

Here are some of the pros I have observed:

  • Using Git and Markdown
    1. Version control is built-in
    2. Markdown is quite powerful and easy to edit
    3. Syntax highlighting of code samples (bash, XML, JSON, text etc.)
    4. The flow resembles a development flow and the toolchain is somewhat the same
    5. Tagging of versions and complete history is available
    6. An engaging proces supporting pull-requests (oh well)
    7. Branching for new editions and proposals for change requests

Currently one of the specification has 4 branches, when evaluation and review is finalized, will be merged onto the master, which can be tagged as the authoritative specification – and this proces is so easy to grasp and complete since it is same proces we use for source code.

One last benefit I really enjoy, one which I think is a bit underestimated is – the contract.

When we publish a public specification, we aim at to be informative, useful, correct, exact, educational, clear and to the point.

This works quite well and since often I find that we refer to the public specifications when discussing topics related to our services and since the quality of these sometime outshine our internal specifications, I often find myself thinking that we should publish much more, much much more.

So revisiting the opening paragraf – ever so often we are afraid and publishing API’s become a side-project. Do not be afraid to publish your specifications and documentation, do not be afraid to use an existing platform and toolchain, the pros outweigh the cons and you will quickly forget all about the old way of doing things and you will find yourself more productive and in the end getting your specifications published will be easier than ever.

Whether you are publishing a website or a PDF document, the information is public, the proces is actually the most important aspects and Github and Markdown REALLY leverage this.

The discussion on how far you can go and how much you can publish is a huge topic and should perhaps be another blog post.

Public Specifications FTW