Skip to content
PROCTOR Form 0.5.0
Menu

Upgrading#

PROCTOR is the invigilator, so upgrading it is a seat change, not a new exam: same hall, fresher pen. This page tells you how to move an app from one PROCTOR release to the next and which changes affect your runs. Start with the release that has a break, then work down to the additive ones.

Unreleased#

Not released yet. This is a pre-1.0 behavior change for consumers on ^0.5: everything keeps working, except that one refusal can turn a passing pipeline into a failing one.

Breaking#

  • composer-audit fails when the composer executable is not on PATH or the app has no composer.lock (rule id proctor/composer-audit/skipped, message starting with not audited:). An app whose audit could not run used to pass with an info line; it now exits non-zero until Composer is installed, the lock is committed, or an active composer-audit override with a reason and an expiry downgrades the fail to a warning.
  • composer-audit fails each ignore entry in composer.json that no active composer-audit override backs (rule id proctor/composer-audit/unbacked-ignore). An app that silences audit results in its own composer.json used to earn only a count warning; it now exits non-zero until every entry is backed by an active override whose advisory field names the entry's advisory id, whose package field matches the entry's package, or that carries no scope at all. Steps: record one such entry per unbacked ignore in policy-overrides.json with a reason and an expiry, keep the composer.json ignore until the override expires, then remove the ignore entry.
  • Refused --policy and --today in CI. In CI (any of CI, GITLAB_CI or GITHUB_ACTIONS set to a value other than 0 or false), proctor check now refuses --policy and --today with a tool error (exit 2) unless the job sets PROCTOR_ALLOW_OVERRIDES=1. In CI the policy and the date must come from the stack, not from the app being checked: a pipeline that could pass its own policy or date could grade itself. Pipelines that pass these options must either set PROCTOR_ALLOW_OVERRIDES: "1" as a variable of a trusted job (a protected or group-level CI variable, never the app's own .gitlab-ci.yml) or drop the option: name the policy with the PROCTOR_POLICY environment variable instead of --policy (it stays allowed in CI), and drop --today or let the trusted job allow it. Outside CI nothing changes.

Changed#

  • An app that failed only because of a dev-only advisory now warns instead. An advisory on a package that composer.lock lists only in packages-dev is a warning at any severity, with the message ending in [dev dependency]; a name in both lists counts as runtime and still fails at or above the threshold. No action is required unless you want the dev dependency updated, because dev tools run in CI.

Deprecated#

  • None recorded so far.

Steps#

  1. Re-run the check in CI and read any Refused: message first:

    vendor/bin/proctor check

  2. For each refused option, either set PROCTOR_ALLOW_OVERRIDES to 1 on the trusted job (GitLab: group Settings, CI/CD, Variables, scope Protected), or drop the option and name the policy with PROCTOR_POLICY.

  3. Make sure Composer and composer.lock are present where the check runs, or record a composer-audit override.

How to verify#

  • Run vendor/bin/proctor check in CI: the run reaches the checks when no refused option is present, or the trusted job sets PROCTOR_ALLOW_OVERRIDES=1.
  • Confirm the refusal names only the option or options that were given (Refused: --policy is not accepted in CI, ..., Refused: --today is not accepted in CI, ..., or both named together).

0.5.0#

Released 2026-11-03. This is a pre-1.0 minor: consumers that pin ^0.4 stay on 0.4.x until they move their constraint to ^0.5. Most of what is new warns and never fails, but one check can now turn a passing run into a failing one.

Breaking#

  • composer-audit fails when composer audit runs but its output is not parseable JSON (rule id proctor/composer-audit/could-not-run, message starting not audited:). A run that audited nothing used to pass quietly; it now exits non-zero, so an app whose audit cannot run will go red until the audit is fixed.
  • Consumers that pin ^0.4 stay on 0.4.x until they move their constraint to ^0.5.

Deprecated#

  • None recorded for this release.

Steps#

  1. Move the PROCTOR constraint in your composer.json from ^0.4 to ^0.5.

  2. Apply it with the install command from the README:

    composer require waynestate/proctor --dev

  3. Re-run the check, and read any not audited: failure first:

    vendor/bin/proctor check

How to verify#

  • Run vendor/bin/proctor check --format=json and confirm the version field reads 0.5.0.
  • Confirm the new warnings appear where they apply. They warn and never fail:
    • composer-config warns when composer.json switches Composer's dependency policy off (proctor/composer-config/policy-off, policy-malware-off, policy-advisories-off).
    • ci-pipelines warns when the pipeline environment switches Composer's audit or blocking policy off (proctor/ci-pipelines/composer-audit-off).
    • composer-audit also counts ignore entries under config.policy (proctor/composer-audit/ignore-entries), and a policy override may name one advisory or package.

0.4.0#

Released 2026-11-03. This is a pre-1.0 minor: consumers that pin ^0.3 stay on 0.3.x until they move their constraint to ^0.4. The new checks warn and never fail.

Breaking#

  • Consumers that pin ^0.3 stay on 0.3.x until they move their constraint to ^0.4. That constraint move is the only break in this release.

Deprecated#

  • None recorded for this release.

Steps#

  1. Move the PROCTOR constraint in your composer.json from ^0.3 to ^0.4.

  2. Apply it with the install command from the README:

    composer require waynestate/proctor --dev

  3. Re-run the check so the new checks take part:

    vendor/bin/proctor check

How to verify#

  • Run vendor/bin/proctor check --format=json and confirm the version field reads 0.4.0.
  • Confirm the checks added in this release appear in the report. They warn and never fail, so the exit code of a run that passed before should not change:
    • composer-audit reports the count of audit ignore entries (proctor/composer-audit/ignore-entries).
    • overrides warns when an active entry matches no failure (proctor/overrides/unused).
    • unbounded-constraints warns on a repository URL that is plain http (proctor/unbounded-constraints/insecure-url) and on a minimum-stability below stable (proctor/unbounded-constraints/minimum-stability).
    • preflight-pinned warns when a Preflight component is included at a ref that is not a commit SHA, or when an app overrides the script of an included Preflight job.
    • lock-committed warns when the composer.lock content-hash differs from composer.json.

The other released versions (0.1.0 through 0.3.1) record no break in the changelog; they add checks and fixes, and the upgrade command is the same for every move:

composer require waynestate/proctor --dev