May, 2018. Second month of the grant.

We set as the official beginning of the grant April 1st, 2018, which was a Sunday. The official end was, then, May 31st, a Thursday.

Here’s the report on the activities carried out during the month of May.

Issues closed

Here’s the table of issues closed during May. Some of them, the oldest ones, include some comments. The April report has been updated; there was a bug in the glob implementation and prevented it from working.

Using the Perl 6 scripts included in this repo, I have closed more than 80 issues during April:

Issues closed by me and others

I eventually erased the JJ TPF grant label since it seemed to be discouraging people from working themselves on the issues. I just organized myself to close at least two issues per day, as was my initial compromise.

In fact, those issues are, on average, more than 7 month old, or more than 210 days, while the average for the rest of the contributors is a bit more than ~1 month.

And that’s mainly due to the fact that issue #114, which was 1000 days old, was closed by someone else, although I did most of the commits to close it by creating several new pages that were missing from the roadmap since the very beginning.

That means that many of the issues addressed were part of the backlog that was accumulating, and weren’t, in fact, being addressed, making the number of issues accumulate to the tune of a few tens every month. If we look at the general chart with the number of opened and closed issues per month, we see that most months had a positive opened vs. closed balance, which became increasingly dire in the first months after release, creating an upward trend in the total number of open issues.

Total number of open issues

In this chart, the number of open issues is sometimes higher than the real number, which is probably due to the fact that some issues have been reopened and then closed several times. At any rate, it reflects the information returned by the GitHub API.

In fact, this grant has allowed to buck the trend that pushed the number of unsolved issues upward, and in fact has meant the biggest monthly difference between the number of open and closed issues, as can be seen below.

Open and closed issues + difference

In fact, this high number of closed issues has allowed finally to bring the total number of issues below 175 at the beginning of June. This is now the ranking of Perl6/doc issue closer, where I’m tied with the top closer.

Contributions via commits

Last month I contributed more commits than the rest of the authors put together, even when May was the month with the highest number of commits so far in the Perl 6 repository.

Commits by JJ and the rest

Quite a few of those commits were done as part of the May Squashathon. I organized, as indicated in the grant proposal, a small Squashathon in which several local developers participated, working on things like the translation of to several languages. I also created this Howto to make easier the participation in the hackathon.

All in all, contributions via commits for the two months have been this

Month My contributions Total
April 195 410
May 324 593

Other contributions


In general, these two months have been a lot of work, but I have had lots of help in the #perl6 IRC channel, and the community has been quite supportive.

This month of May my intention was more to create new pages and address really old issues, like #114. I have achieved that, with lot of work on creating pages on math and data structures from scratch. This has completed the original roadmap of pages that needed to be created, although the need to create new pages, like the one on statement prefixes, has emerged.

I think that, after these two months of grant, I am in the position of helping even better with the documentation repository, since I know much better most or all outstanding issues and can help newcomers focus on some new ones. After the grant, this is my intention for the (near) future

Some advice for Perl 6 documentation sustainability

Documenting a language is a lot of work; however, I expect to have proved that a single, focused person is enough to clear the backlog of issues and improve documentation in a way that volunteer work rarely covers. This report, which studies issues, tends to show that volunteer work focuses on short term, recent issues, disregarding other, more complicated issues that require longer focus.

This is why a piece of advice is that the foundation, or someone in overall charge of development, should create the figure of designated doccer, to be that person that focuses on old, long-term issues that require that kind of attention, as well as draw the focus of the community to certain issues that might have been disregarded. This person should look at higher level metrics, like file entropy, to find out which files have been disregarded and update or draw the focus of the community to them. It could be a volunteer position or an honorary appointment, but it is something that is really needed in this project.