Announce security rule changes with short, dated release notes that state what changed, who is affected, what will happen to their builds, and how to opt out for a limited time. Post them where developers already look, and give notice before a rule starts blocking.
Why rule changes cause trouble
A new rule, a changed severity or a scanner upgrade can turn a passing pipeline into a failing one with no code change. The developer sees a red build and has no idea why. Each surprise costs trust, and trust is hard to rebuild. Related background is in scan results changed overnight with no code change.
What belongs in a rule change note
Keep each entry to four lines.
| Field | Example |
|---|---|
| What changed | New rule flags unparameterized SQL in the data access layer |
| Who is affected | Services using the shared database helper |
| What happens | Findings show as warnings from 3 November, block merges from 17 November |
| What to do | Use the parameterized helper, or request a dated exception |
Add a link to the rule description and to a place to report a false positive.
Use three stages
- Announce. Post the note at least a week before any blocking behavior.
- Warn. Run the rule in report only mode so people can see their findings without being blocked.
- Enforce. Turn on blocking on the stated date, for new findings first.
If a rule fails the report only stage, for example because most findings were dismissed, do not promote it. Tune it or drop it. The same pattern is described in moving a policy from warn mode to enforce mode.
Where to post
- The channel developers use for platform news, not a security only channel.
- A pinned changelog page with a stable link.
- A line in the pull request check output when a new rule fires for the first time.
One source of truth beats five partial ones. Link everything back to the changelog.
Write like a changelog, not like a policy
Short sentences. Dates written out. No jargon that needs a glossary. Lead with the effect on the reader, then the reason. A good habit is to read the note out loud and ask whether a developer on another team would know what to do.
Include a rollback plan
Say how a change can be reversed. For example: "If more than a set share of findings are dismissed in the first two weeks, we will revert to warning." Developers accept new rules more readily when they can see a safety valve.
Track whether it worked
For each change, record how many findings it produced, how many were fixed, and how many were dismissed as wrong. After a month, post the numbers. This closes the loop and makes the next announcement easier to trust.
Edge cases
Emergency rules. For a rule that responds to active exploitation, shorten the notice period but still send the note. The reason matters more when the time is short.
Vendor changes. If your scanner vendor changes defaults, treat it like your own rule change and post a note on your side.
Custom rules. Version them in a repository and show the change history in the same changelog.
Safeguard policies, gates and guardrails can be configured, so a team can stage a rule from visibility to enforcement. Try a first scan at gold.safeguard.sh/scan.
Quick check
How much notice is enough?
A week is a practical minimum for a blocking change, longer for large teams. Shorten it only for urgent security reasons and say so.
Who should write the notes?
The person who owns the rule, reviewed by a developer from an affected team.
Last reviewed: 19 October 2026.
