Improve the way we track software requirements

[marcbria]

For a sysadmin knowing the requirements to install a software is essential, and currently this in OxS tools can be a bit complicated.

The problems I see are several:

• Lack of info: There are no requirements for OJS 3.4 or 3.2 (still supported?) and no hardware recommendations at all.
• Desynchronization: The recommended version for 3.3 (currently php8.0) is desynchronized with the version being tested (php8.1).
• Update: we currently recommend outdated DB versions like mysql version 4.1...
• Location: appears on a website, when the administrator hopes to find it among the code (common practice in CMS).
• History: When the website is updated, the history information is lost, which does not allow us to know which version was recommended for older versions (or not as old).
• Independent of the tool: All tools are kept on a single page, when in some situations it could be different (this last point could be also thought as a benefit).

Regarding the "Location" issue, explain that this has changed over time:

In new versions it is on a PKP Docs Hub web page (e.g. here), which is good because you can update any time you need... but at the same time it is a problem because you cannot associate versions and releases, the version history is lost and, furthermore, many administrators are unaware of the existence of PKPDocs.

In the old versions we kept the requirements in the README.md file, which on the one hand ties your hands because once released, it cannot be changed, but at the same time it has very positive effects such as maintaining an unambiguous relationship between version and release or forcing you to review the requirements in each release.

Thus, the proposal consists of maintaining the requirements in the code (e.g. README.md) to facilitate its location, and also so that in the future, there are no doubts about the version for which a certain test was performed. This file need to be extended with HW requirements as an orientation to dimension the resources need.

It could also be important to ensure that the release process includes a specific step/check to review this requirements file (including php plugins and any other dependencies).

To facilitate the transition, to maintain backward compatibility (or if it is still considered necessary to keep it as a webpage), in the README.md you can add a link to the PKPDoc website with a note like "Check this for updated information." but the webpage need to be understood as secondary medium to make those requirements visible, not the main source.

Finally, if over time the maintenance of the website is abandoned, we can always link to the README.md and that's it.

[asmecher]

We are currently defining the minimum PHP version in lib/pkp/composer.json, but can also list dependencies on PHP extensions in the Composer config.

It would look like this in lib/pkp/composer.json (using XML and mbstring extensions as examples):

diff --git a/composer.json b/composer.json
index c2f224223f..11ac30a389 100644
--- a/composer.json
+++ b/composer.json
@@ -1,5 +1,7 @@
 {
 	"require": {
+		"ext-xml": "*",
+		"ext-mbstring": "*",
 		"adodb/adodb-php": "v5.20.18",
 		"components/jquery": "^3.5",
 		"components/jqueryui": "1.*",
@@ -43,6 +45,7 @@
 	"config": {
 		"component-dir": "lib/components",
 		"vendor-dir": "lib/vendor",
+		"platform-check": true,
 		"platform": {
 			"php": "8.1.0"
 		},

This results in the generation of a script called lib/pkp/lib/vendor/composer/platform_check.php, which we could call upon from the installer script. If requirements aren't met, it generates a list of error messages. See https://getcomposer.org/doc/07-runtime.md#platform-check for documentation.

(Composer also supports a composer check-platform-reqs verb -- but I didn't find it as useful.)

[asmecher]

I've added ext-xml, ext-mbstring, ext-intl, and ext-zip to the Composer config; these can now be checked using composer check-platform-reqs.

[asmecher]

And I've also set platform-check: true in the Composer config, which will make extension checks happen during Composer autoload. I think the overhead for this shouldn't be appreciable. https://getcomposer.org/doc/06-config.md#platform-check

[asmecher]

@marcbria, my preference would be for us not to maintain a list of required modules. That's because it'll likely fall out of date, and because so many of the required modules are defined by 3rd-party dependencies that may change.

Instead, I would prefer that we add...

1. Automated checks -- this is now covered using Composer
2. Recommending a tool that lists requirements -- this can be done using composer check-platform-reqs

This combo allows the set of requirements to be calculated from the dependencies (though some are specified manually in the Composer config) rather than being maintained once in the code and again in the recommendations.

If that's OK with you, then all that's left is to update the documentation to point to the check-platform-reqs Composer command.