3SD handbook

CiviCRM core and extension overrides

Where possible we try to avoid making overrides to core files, but sometimes this is necessary. This page outlines our approach to this.

It is important that we keep careful track of these overrides so that we can update or remove them when we perform a CiviCRM upgrade.

CiviCRM core overrides

If the override is to fix a bug in CiviCRM, we should raise an issue to make others aware of this issue (if it doesn't already exist). If possible we should also create a pull request (PR) or merge request (MR) to fix the issue.

Core overrides should go into a separate extension specifically for this purpose named "[Client] core overrides". This should only include core overrides and not any other client specific customisations.

The extension should include a README.md file that details each of the overrides with the following information:

  • Title of override
  • Short description of what the override does and why it is necessary
  • Link to issue in 3SD GitLab
  • Link to MR or commit in 3SD GitLab
  • Link to core issue on CiviCRM's GitLab (where relevant)
  • Link to core PR in GitHub (where relevant)
  • Expected version of CiviCRM that the PR will be included in (if known)

The client wiki should have a page for core overrides which should link to the README rather than duplicating the content of the README. (It is easier to maintain the documentation of core overrides in git rather than the wiki.)

CiviCRM extension overrides

As above, if the override is to fix a bug in the extension we should raise an issue with the extension and if possible create an MR/PR to fix it.

It isn't practical to put extension overrides into a separate extension so these overrides need to be made directly to the files in the extension. This means that they are likely to be lost next time the extension is updated so it is important that we keep track of these overrides in the wiki.

The client wiki should have a page for extension overrides with similar details to above:

  • Name of extension
  • Short description of what the override does and why it is necessary
  • Link to issue in 3SD GitLab
  • Link to MR or commit in 3SD GitLab
  • Link to issue raised with the extension
  • Link to MR/PR for the extension
  • Expected version of extension that the MR/PR will be included in (if known)

CMS overrides

It is less common to make overrides to the CMS or CMS plugins/modules. Where this has happened we should create a page in the client wiki detailing these overrides in a similar way to above.