Standards

Appearance

Project maintenance ​

Projects should be regularly maintained to keep dependencies up to date and proactively address code quality issues.

Performing maintenance regularly is vital for web application security. It also avoids costly large-scale upgrades in future.

Cadence ​

Quality-assured workflow projects ​

For projects following the quality-assured workflow, maintenance releases are required to be performed regularly. Performing maintenance under a specific release ensures regressions can be isolated from other code changes.

The exact cadence of maintenance releases can vary depending on the project, however a typical approach is to make 1 in 3 releases a maintenance release.

Basic workflow projects ​

A process for basic workflow projects is not yet defined. For now, developers are encouraged to perform maintenance as time allows, particularly prior to implementing larger pieces of work.

Scope ​

Minor dependency upgrades: always ​

Every maintenance release should include minor dependency upgrades:

bash
# Update back end dependencies
composer update

# Update Yarn
corepack use yarn@stable

# Update front end dependencies
yarn upgrade

Ensure lints and tests still pass, and the front end still builds.

Security vulnerabilities: always ​

Every maintenance release should also include a vulnerability audit:

bash
# Audit back end dependencies
composer audit

# Audit front end dependencies
yarn npm audit

Upgrading dependencies will resolve most reported vulnerabilities where a fix is available, but this isn't guaranteed: a fix may only be available in a major version that would otherwise be deferred (see below), or the vulnerable package may be a transitive dependency that isn't touched by composer update/yarn upgrade. Running an audit confirms whether anything remains outstanding, and should raise the priority of any deferred major upgrade that resolves a known vulnerability.

TIP

For Composer dependencies, composer update -Wm performs the minimal update needed to resolve known security issues. Composer's own audit check can sometimes block this by flagging the very vulnerabilities it's meant to fix; if so, temporarily ignore the relevant CVE codes via the config.policy section of composer.json.

Major dependency upgrades: check and evaluate ​

Check for major dependency upgrades. For each major upgrade, check the published changelog and/or upgrade guide. If the upgrade path is straightforward and will have minimal impact, action it. Otherwise, record the necessary steps in a Jira ticket for prioritization in a future release.

For Composer, run composer outdated -DM to list direct dependencies with a major update available. For each dependency, if the decision is to update it, run composer require <package> -W. For example:

bash
composer outdated -DM
composer require outdated/package -W

Yarn provides an interactive upgrade tool:

bash
yarn upgrade-interactive

Follow the instructions to select and upgrade packages.

Major platform dependencies, such as Laravel or Statamic, always require a dedicated release – see Major platform upgrades below.

Error log: check and evaluate ​

Check error logs and monitoring tools, if available, for recurring exceptions and performance issues.

If a straightforward, minimal impact fix can be implemented, do so. Otherwise, record it in a Jira ticket for prioritization in a future release.

TIP

For Laravel projects, Laravel Pulse is a good basic monitoring tool. It should be installed and accessible only to appropriate signed in users, such as morphsites® developers.

Major platform upgrades: dedicated release ​

Major platform upgrades typically occur once a year. These include:

  • PHP
  • Node (LTS versions only)
  • Laravel
  • Statamic

These upgrades should be planned in advance and performed in a dedicated release.

It is wise to allow a period of time (e.g. one to two months) before adopting a major platform version. This allows issues to be resolved and the ecosystem to stabilize.