How to document our minimum module versions

[Gervase Markham]

Our documentation currently attempts to tell people the minimum version
of the required and optional Perl modules they will need. However, there
is a problem. The .rst file which contains this info is built by
makedocs.pl - and makedocs.pl is not run when the docs are compiled by
ReadTheDocs. So the substitution values are not available. The result
looks like this:
http://bugzilla.readthedocs.org/en/latest/modules.html
(Note that this is not the mainline install docs; it's designed for
manual install of Perl modules.)

This problem is:
https://bugzilla.mozilla.org/show_bug.cgi?id=964849

The version data is stored in Bugzilla/Install/Requirements.pm. The
initial solution which suggests itself is to write a parser for the
Requirements.pm data structures in Python. However, these are not
straight data structures. The minimum version of some modules depends on
whether you are on Windows, and for others it depends on your Perl
version. (This leads to bug 428793, which notes that the docs can lie to
you about the required minimum version if they were compiled on a
computer with a different OS or Perl version to your own.)

So, it seems to me that, if we want to continue to have this info in the
docs, the best fix is to remove that data and place it in a JSON file,
which can be parsed by either Perl or Python. That file could have a
specific section for the differing requirements of Windows. If the
varying minimums depending on Perl version are still required, it could
also have a way of indicating when the minimum version depended on your
Perl version, and what the options were. The docs would then attempt to
explain all this to the user.

However, this would be a reasonable amount of work.

Another possibility is to remove this information from the documentation
entirely, and require that people run checksetup.pl --check-modules on
their target system in order to get it. (Running with --check-modules
has no side effects and does not take any installation steps.) This
would be the simplest fix, and is preferable if it's acceptable to
people. Given that running checksetup is a required step for
installation anyway, it's not a hardship. If people wanted a printed
list, we could even link them to the relevant code in our BZR repo, as
the data structure is not hard to read for a human.

I'd prefer to do the latter, but welcome your comments.

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla at lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-apps-bugzilla