Modernization

[ajmalton]

Good, yes, we can talk here.

Modernizing the code initially requires global (not localized) changes. Even if the changes are tiny. There is so much to do! and the structure is rather brittle with age and global variables.

As long as the structure is so entangled, I don't see how we can make progress with anything else.

So I think the jobs, in order, are

1. Move to use strict and use warnings 'all', everywhere.
2. Package and module horas:: and missa:: according to the existing file structure.
3. Reorganize those modules to reflect the "request to options to ordo to content to hypertext to response" pipeline
4. Move to use Exporter properly.

Question: is this right, and in the right order?

This is lots of refactoring. Number 1 involves (discovering and) declaring which variables are my and which are our; and an assortment of other little things that might get warned. Number 2 involves renaming the "module" files from eg horascommon.pl to horascommon.pm (even if no export specifications are introduced).

Question: is anything currently being done that may conflict badly with these?

Now long ago I wrote some scripts for regression testing: they're in admin/ of all places: but they still seem to work. I see there's some prove support, and some Travis, as well.

The above is all refactoring, no external functional changes. It should be possible to verify byte-for-byte identity at the HTTP level.

Question: how do you all currently do testing?

[ajmalton]

It's a lot of work, though. And just a start. Is it worth it? Is there a better path? Is continued maintenance as-is a reasonable alternative?

[gregordick]

To get to a more maintainable codebase, that sounds like a good plan to me. I'd be inclined to add unit tests in stages 2-4.

Whether it's worth it is the critical question. Currently, fixing bugs is hard, and adding features almost impossible. This would be improved no end by implementing the plan that you describe, but (a) I would reckon that this is several man-months of work, and (b) the architectural deficiencies (assignment of propers to days rather than to offices, hardcoding of assumptions about languages and versions, etc. etc.) would still remain to be addressed.

I did a tiny bit of the refactoring that you describe a few years ago on the calcalc branch, but probably nothing that's worth reusing.

As regards testing: Once upon a time I would use a wrapper around divinum-replay.pl that generated all of the offices for three years. I (or actually a Jenkins instance running on my desktop at the time) maintained a local git repo of the output, which I could eyeball for regressions. I started writing some unit tests on the calcalc branch for the new code.

[ajmalton]

Unit tests could exist after 3. Unfortunately, the nine files that would become "modules" during 2 can't really have specifications until they're reorganized. Hence they can't have unit tests. Of course afterwards there might be only six.

[mbab]

So I think the jobs, in order, are

1. Move to use strict and use warnings 'all', everywhere.
2. Package and module horas:: and missa:: according to the existing file structure.
3. Reorganize those modules to reflect the "request to options to ordo to content to hypertext to response" pipeline
4. Move to use Exporter properly.

Point 0. should be as:
0. Equate perl version on server and Dockerfile

[ajmalton]

The dockerfile is from perl:5.28-slim. Is the system running somewhere with a different perl than that?

Do we know what version the code wants or needs? I have been adding use v5.14 statements as well as specifying strictures and warnings. I have v5.32.1 for development.

[mbab]

@APMarcello3 reported Perl is v. 5.18.4. in September

[ajmalton]

I have experimentally revised horas::officium and horas::webdia and horas::horascommon to operate under stricture and warnings. I have introduced new our declarations for this purpose, as required by each file. There are almost 100 global variables!

A small number of global ish names are able to be my in each file. (A couple really seemed to have to be state. Sigh.) I have not been trying to put individual our declarations in each sub, but only in each module. That's a smaller change increment and less error-prone.

The module horas::dialogcommon seems to be in a different style: more modular... global declarations in each sub... much smaller subs. Was someone else the author, I wonder? Or was it refactored already by someone?

My work is posted to a branch in my GitHub.

[fiapps]

The git log shows Gregor Dick was responsible for most of the refactoring, and this matches my recollection. git blame shows lots of lines modified by Martin Hasoň, but that was just perltidy.

[ewcole]

I think that it would be a big improvement if we tried to make the output into semantic HTML by adding meaningful classes. That way, we could bolt on a converter that could turn the output into XML or some machine-readable format.

[ajmalton]

Certainly it would. Probably "semantic HTML" would be a good target. That's a natural goal of modernization even though semantic HTML is almost as old as our project is.

Making the output more closely reflect the content could make (or at least allow) the code to be simpler and more robust, too.

However modularization (a value decades older than semantic HTML) needs to be imposed first, because : with over 17000 lines of ancient perl, 130 global variables, 309 subroutines not one of which depends only on its parameters, 65 uses of eval(), and all the processing stages tangled together, modifying it is at present a rather delicate business.

(This project captures the historical rules of the Roman Rite in a formal structure, and as such is a valuable legacy (if a bit niche). We must proceed carefully with changes. Would that every custodian of the Rite would similarly preserve its forms with care!)