Rule types

Rules define how Planekeeper measures version staleness. Each rule type calculates a “behind by” value and compares it against three severity thresholds you configure: moderate, high, and critical.

How thresholds work

Every rule has three threshold tiers. Thresholds must be ordered from smallest to largest:

The highest matching threshold wins. If the behind-by value is below the moderate threshold, no alert is generated.

Example: A rule with thresholds moderate=7, high=30, critical=90:

• Behind by 5 days: no alert
• Behind by 10 days: moderate alert
• Behind by 45 days: high alert
• Behind by 100 days: critical alert

Days behind

Alerts when your deployed version was released more than N days ago, measured from the deployed version’s release date to today.

Parameter: max_days (set via the three threshold fields)

How it calculates:

1. Look up the release date of your discovered (deployed) version in the upstream releases
2. Calculate the number of days between that release date and today (time.Since(deployedReleaseDate))
3. Compare against your thresholds

The latest version’s release date is not used in this calculation. Only the deployed version’s release date and the current date matter.

Example (assuming today is Mar 15):

With thresholds of moderate=30, high=60, critical=90:

• Version 1.25.0: 45 days since release = moderate
• Version 2.0.0: 5 days since release = no alert
• Version 3.1.0: 99 days since release = critical

Majors behind

Alerts when your deployed version is N or more major versions behind the latest release.

Parameter: max_majors (set via the three threshold fields)

How it calculates:

1. Parse both your deployed version and the latest version as semantic versions
2. Subtract the major version numbers: latest_major - deployed_major

Example:

With thresholds of moderate=1, high=2, critical=3:

• Version 1.5.2 vs 3.1.0: 2 majors behind = high
• Version 2.0.0 vs 2.9.5: 0 majors behind = no alert
• Version 5.3.1 vs 8.0.0: 3 majors behind = critical

Minors behind

Alerts when your deployed version is N or more minor releases behind the latest. This rule counts actual releases, not version number gaps.

Parameter: max_minors (set via the three threshold fields)

How it calculates (preferred method):

1. Collect all upstream releases between your deployed version and the latest
2. Count unique major.minor combinations in that range
3. Use that count as the behind-by value

This means skipped version numbers do not inflate the count. If a project releases 1.1, 1.2, 1.5, and 1.8 (skipping 1.3, 1.4, 1.6, 1.7), only four minor releases are counted.

Example with release-list counting:

Available releases: 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 3.0.0, 3.1.0

Fallback calculation:

When the full release list is unavailable, Planekeeper uses a formula:

• Same major version: latest_minor - deployed_minor
• Different major versions: (latest_major - deployed_major) + latest_minor

This is an approximation and may overcount when major version boundaries are crossed.

Stable-only filtering

Enable the stable_only flag on a rule to ignore prereleases when determining the latest version. When enabled, Planekeeper skips any release whose version string contains:

alpha, beta, rc, dev, snapshot, canary, nightly, pre

The check is case-insensitive, so 1.0.0-RC1, 2.0.0-beta.3, and 3.0.0-SNAPSHOT are all treated as prereleases.

Example:

Available releases (newest first): 5.0.0-rc1, 4.2.0, 4.1.0, 4.0.0

Choosing the right rule type