Peter Rabbitson sent me this idea:

I can not think of anything qualifying as doesn't have to be a huge Perl project* However, I have an idea which unquestionably will benefit the Perl community immensely, yet has a remarkably low barrier to entry (mainly one thing - patience). I propose that someone applies for a grant in the role of DBIx::Class re-documentation project lead.

I have had inklings of "there got to be a better way to do things", but it wasn't until I read this meditation by BrowserUK that it dawned at me: Fixing up the better-than-most-but-still-terrible documentation of DBIC is a ~200 person-hour undertaking, which on top of that requires someones fresh eye. Given that DBIx::Class is a "staple-module" in the contemporary Perl ecosystem, I believe it is reasonable to expect for the TPF to "pick up the tab" if someone with the right qualifications steps up.

So what is wrong with DBIC's documentation anyway?

• Lack of entry level architectural documentation steering a beginner towards most effective use of this library
  • It is not clear DBIC is not exclusively an ORM
  • It is not clear what is the primary problem it is intended to solve
• Lack of a consistent overarching approach to the subject - the current docs are riddled with localized fixups, completely ignoring the "larger picture". As examples consider:
  • https://github.com/dbsrgits/dbix-class/pull/21#issuecomment-15849436
  • https://rt.cpan.org/Ticket/Display.html?id=63843#txn-867585
  • or perhaps https://rt.cpan.org/Ticket/Display.html?id=83767#txn-1188058
• Lack of documentation clearly delineating the components, and extension points
  • Lack of clarity what is and what isn't safely overrideable
• Too many "learn by doing" tutorials, unaligned and sometimes even conflicting with each other
• Lack of proper versioning markers in the reference documentation (X available since version such and such)
• Lack of consistent documentation of method signatures
• Inconsistent/incomplete exception texts: Ideally a DBIx/Class/Diag.pod modeled on 'perldoc perldiag' as a central exception text repository (though note - categorically no exception objects)
• Worst part - a number of other problems that I am completely unaware of, as I know the source code inside-and-out, and can only notice the "disconnect" based on questions being repeatedly asked on IRC So what would the ideal candidate for the job would look like?
• You have general familiarity with Perl conventions and "perlish documentation practices" You have decent understanding of SQL, ideally being able to follow this presentation in its entirety
• You are able to dedicate large contiguous blocks of time to the project
• You are not afraid to ask followup questions and followups to the followups, until you have a solid understanding of the thing you are actually trying to document.
• You have little experience with DBIx::Class - this is not a typo: the cleaner your slate is when starting, the better you will be able to grasp the very essence of this library and be able to present in a language accessible by those who will be consuming your work in the future. I believe the work needs to at least be able to capture things like:
  • DBIC is decidedly not a classic ORM
  • DBIx::Class::Core is an under-designed reference implementation
  • DBIC in no way mandates a properly designed schema
• You are patient
  • It is of paramount importance to ensure that the documentation does not become worse than it is now. This will likely involve multiple iterations to ensure code and documentation agree (in case of disagreement code always wins, but the goal is to eliminate all such mismatches in the first place)
  • Moreover it is quite likely that your work will not show up on CPAN several months (up to a year) after the grant is successfully completed. The library is the bedrock of hundreds of businesses worldwide, hence the current architect is extremely conservative in both matters of code and docs. What will the project provide to a successful/approved applicant?
• Authority to demand full and timely answers to any questions you they have arising from the current documentation, code, or comments.
• Unlimited access to a person with complete (as in "familiar with every single line") knowledge of the codebase. What else is missing?
• Probably a grant manager - while being versed in all things perl5, I am rather terrible at progress reports, and other bureaucracy. Besides the "unlimited access to answers" will keep me busy enough as it is.

So... any takers? Praises? Flames? :)))

Cheers Peter "ribasushi" Rabbitson Principal DBIx::Class cat herder

* In fact I strongly believe that work taking "a few weekends" can not possibly benefit the community, and framing the requests this way actively hurts the grants but that's a whole another topic.

Alex aka ASB gave me this proposal:

We (the Perl community) currently do not have a CPAN module that handles OData (cf. odata.org). There seems tob e an attempt to do it here: OData::Client But it's not finished yet, and i fit doesn't get a care taker, it will never be done. Also, there is client and server parts. Let's get both :)

Side node: Eventually, I'm too dumb to see that we don't need one because Perl can do it out oft he box. But if this ist he case, eventuelly, it would be a good idea to put up a grant to create a document describing how to use OData with Perl (like this one)

Somebody asked me:

Is the Foundation mainly interested in grants to help fund work on Perl's own infrastructure -- the language itself, key modules, and other community projects -- or would it also be open to considering funding open-source applications created with Perl, but which don't primarily exist to support Perl itself? (And which, perhaps, might help further Perl's reputation, and provide the world with more high-quality example code?)

Our grants program does not specify such scope. So our official answer is: "just send a proposal for review". I also went through the historical grants, both approved and rejected, and found no grant proposals in this area.

Anyway, even without specific grant proposals, I thought it would be interesting to ask this question to the public. Should we fund application development Perl?

I think it's a good thing for the Perl community to support software development in Perl. For instance, if somebody writes a face recognition website in Perl and gets one million visitors, it'll be a good exposure for Perl itself. There's no reason to limit the program to the "infrastructure" = bottom of the Perl development stack.

Will it fit in the existing grants program? Unlike developing a Perl module with promised features, it may not be straightforward to quantify value of such development activities until it's released and used. It can well fit in the grants program if the deliverable is well quantified.

What's your view?

(P.S. I see some people can't comment at blogs.perl.org. If you have an issue, feel free to email to me so I can publish your comments here)

Merijn Brand gave me this proposal. As it’s too long for our grant ideas list, I am posting here.

Currently, pack and unpack work on a string, which means that you have to move forward in the data-string yourself, if the full data-format is not known in advance, but depends on data seen so far.

If one could unpack on a stream, one could unpack the picture that is known, have the stream pointer move forward the amount of data read from the given picture, and be ready to read the next data based on a next, possibly different) picture.

Extreme “win” can be taken where the size of the data being read for a given picture is differing per architecture, like native floats.

From PerlMonks thread http://www.perlmonks.org/?node_id=1104462

Perl Monks, I humbly seek your wisdom: I wish to unpack a series of strustures from a binary file. I have used:

@array = unpack (“f*”, join (“”, <$filehandle>));

to load an array of floats into memory from a smaller binary file, but a) This file is too big to fit in memory b) It has a complex structure, like “int, int, float, float, float” repeating.

How shall I iteratively unpack the next structure from the file into a list of scalars, without loading the whole file into memory?

[ikegami] came with this solution:

my $template = "iifff";
my $rec_size = template_len ($template);
while (1) {
my $rv = read ($fh, my $rec, $rec_size);
defined $rv or die “$!\n”;
$rv or last;
$rv < $rec_size and die “Premature EOF\n”;

my @fields = unpack $template, $rec;
…
}

which does not show the required template_len function that needs to calculate the actual data length for a given picture (possibly by using the picture to pack data into a string and ask for its length).

Having the suggested functionality, that code could be simplified to

while (my @fields = unpack “iifff” => $fh) {
…
}

See also this thread on perlmonks: http://www.perlmonks.org/?node_id=1099544 where attached PM-1099544-0.pl has been rewritten to PM-1099544-1.pl first to make the code easier and readable, and then - given unpack on streams were possible - rewritten to PM-1099544-2.pl This example is just eliminating 3 read calls

If you need the attached *.pl files, contact Merijn or me.

I made a list of grant idas. Nothing fancy but it's just a start.

Share grant ideas. Use the ideas. Improve Perl.