(dev/drupal#10) Make civicrm-version.php self-sufficient

[totten]

Overview

The file civicrm-version.php has traditionally been a generated file. However, this is an impediment to composer-based deployment. The PR aims to allow one to use a static, non-generated copy of civicrm-version.php.

This PR is a continuation of @monishdeb's #12016 -- while testing that PR, I ran into various issues which were cumulatively easier to patch than to discuss. Each is presented as a separate commit (with description) in this PR.

Before

• Tarball-based installations use a civicrm-version.php generated by distmaker.
• Git+composer based installations use a civicrm-version.php generated by GenCode.

After

• The file civicrm-version.php includes a deprecation notice.
• Tarball-based installations use a civicrm-version.php generated by distmaker (same as before).
• Git+composer based installations use a static civicrm-version.php from git. This file will:
  • Read the version number of xml/version.xml
  • Autodetect the CMS -- first, checking PHP constants for signs of an active CMS; if that fails, then checking the filesystem for distinctive files.

Technical Details

The static file relies on CMS autodetection -- it should work in most cases, but fundamentally autodetection depends on the environment, and there are some cases where CMS autodetection doesn't work. This will arguably be a compatibility break for someone, but there's a number of mitigating factors.

1. In universe, almost nobody relies on civicrm-version.php to report the CMS -- the only known use-cases are (a) displaying an informational field in the installation UI and (b) the drush civicrm-install command (for Drupal variants).
2. As part of my testing of (dev/drupal/10) Make civicrm-version.php self-sufficient to fetch Civi version and CMS name #12016 (which drove the updates here), I tried using civicrm-version.php in multiple CMS's (D7/WP/BD) and in multiple uses (listed below).
3. For anyone who builds on top of the tarballs (probably most people), the file is still generated by distmaker.
4. The file is now marked deprecated.

So I spent a lot of time on testing civicrm-version.php, namely doing each of these in D7/WP/BD:

• (a) Using civicrm-version.php with adhoc PHP in an unbooted environment
  • (a1) php -r 'require "civicrm-version.php"; $a = civicrmVersion(); print_r($a);' (borrowing a bit from civi-test-run)
• (b) Using civicrm-version.php through an intermediate file (/tmp/ver.php which does the same as above) in an unbooted environment
  • (c1) php /tmp/ver.php
• (c) Using civicrm-version.php with adhoc PHP in a booted environment
  • (c1) drupal ev 'require "'$PWD'/civicrm-version.php"; $a = civicrmVersion(); print_r($a);'
  • (c2) `wp eval ev 'require "'$PWD'/civicrm-version.php"; $a = civicrmVersion(); print_r($a);'
  • (c3) cv ev --level=cms-only 'require "'$PWD'/civicrm-version.php"; $a = civicrmVersion(); print_r($a);'
• (d) Using civicrm-version.php through an intermediate file (/tmp/ver.php) in a booted environment
  • (d1) drush scr /tmp/ver.php
  • (d2) wp eval-file /tmp/ver.php
  • (d3) cv scr --level=cms-only /tmp/ver.php
• (e) Opening the installer UI and checking the version+CMS in the top-right.
• (f) Usingdrush civicrm-install
  • (This was only partially tested because the options are weird to test in a dev context. However, after hacking around to try it in a dev site, I eventually figured that (b)/(d) were decent predictors of how well drush civicrm-install would work.)

The static civicrm-version.php reported version# correctly in all scenarios that I tested. However, the CMS reporting is a little flaky with unbooted environments (a+b) because they depend on a filesystem scan -- but the start-point for the filesystem scan depends on happenstance (how exactly you call it) and the validity of the scan depends on your system configuration.

This is arguably a compatibility break, but honestly -- I'd rather kill the CMS-reporting than spend any more time getting the CMS-reporting to work in unbooted environments. It's just not used much, and it's brittle by design. That's why I've marked civicrmVersion() as deprecated. But for the moment - normal tarball users should be getting exactly the same as before, and git/composer users should have something that works in the real/known use-cases (e,f).

[monishdeb]

Thanks @totten . I have tested the patch and followed each step you have mentioned. Checked with rebuilt tarball and its working fine.

[totten]

@eileenmcnaughton @colemanw - A procedural question on merging: Monish and I have both put in SLOC/commits here, and we've both reviewed the others' commit. On the merits, I think it's seen a good chunk of review, but hitting "Merge" would technically be a self-merge, so I want to make sure the record is persuasive. You think we're OK to merge? Or should we put it through some other step?

[eileenmcnaughton]

@totten right - this is a constant issue - when we collaborate we are implicitly reviewing each other's work but then we don't feel able to merge the result. I have experienced this problem a lot & TBH what I do is convince the other party to resubmit the whole lot with my commits squashed in to pass the letter of the law without it being meaningfully different.

I don't have an answer to the bigger issue - but I will merge this based on the knowledge that you @monishdeb are satisified with it that is enough for me.