docs: 3.3.x upgrade notes for the three deduplication identity changes - #15761
Merged
Conversation
The 3.3 upgrade page said "no special instructions", which this release makes wrong three times over: Xeol Parser, Checkmarx One Scan and Checkmarx Scan detailed all gain HASHCODE_FIELDS_PER_SCANNER registrations, so findings imported before the upgrade carry hashes that no longer match what an import computes after it. Follows the shape the 3.2 notes set: what changed and why per scan type, then two paths. Instances running the identity signature ledger (default from Pro 3.2.300) need no action because drift detection, the scoped rehash and signature matching bridge the change; the one caveat spelled out is that a large never-backfilled instance should run the backfill before upgrading, since a rehash replaces the identities the backfill exists to record. Everyone else gets the three manage.py dedupe commands in the same form the 2.4x and 3.2 notes use.
The Pro section overpromised twice. It claimed both ledger flags default on in 3.2.300, and matching is deliberately opt-in. It also claimed the definition change is repaired automatically, but identity_drift_watch notifies and stops there; the repair is the operator accepting the change or running the same dedupe commands everyone else uses. Rewritten so the Pro path is honest: recording is on by default, the drift watch will tell you, and the fix is the same three commands or a Tuner acceptance. The backfill-before-upgrade guidance stays, scoped to instances where matching is enabled, because that is where the preserved identities are actually consulted.
Contributor
Author
|
Amended after the default-flip attempt on the Pro side surfaced two inaccuracies in the first cut of this page:
|
blakeaowens
approved these changes
Aug 22, 2026
Maffooch
approved these changes
Aug 22, 2026
devGregA
added a commit
that referenced
this pull request
Aug 22, 2026
#15761) * docs: 3.3.x upgrade notes for the three deduplication identity changes The 3.3 upgrade page said "no special instructions", which this release makes wrong three times over: Xeol Parser, Checkmarx One Scan and Checkmarx Scan detailed all gain HASHCODE_FIELDS_PER_SCANNER registrations, so findings imported before the upgrade carry hashes that no longer match what an import computes after it. Follows the shape the 3.2 notes set: what changed and why per scan type, then two paths. Instances running the identity signature ledger (default from Pro 3.2.300) need no action because drift detection, the scoped rehash and signature matching bridge the change; the one caveat spelled out is that a large never-backfilled instance should run the backfill before upgrading, since a rehash replaces the identities the backfill exists to record. Everyone else gets the three manage.py dedupe commands in the same form the 2.4x and 3.2 notes use. * docs: the drift watch reports, it does not repair The Pro section overpromised twice. It claimed both ledger flags default on in 3.2.300, and matching is deliberately opt-in. It also claimed the definition change is repaired automatically, but identity_drift_watch notifies and stops there; the repair is the operator accepting the change or running the same dedupe commands everyone else uses. Rewritten so the Pro path is honest: recording is on by default, the drift watch will tell you, and the fix is the same three commands or a Tuner acceptance. The backfill-before-upgrade guidance stays, scoped to instances where matching is enabled, because that is where the preserved identities are actually consulted.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The 3.3 upgrade page currently says "no special instructions". This release changes the stored identity of three scan types, so that is wrong three times over.
Xeol Parser,Checkmarx One ScanandCheckmarx Scan detailedall gainHASHCODE_FIELDS_PER_SCANNERregistrations in 3.3.0. Findings imported before the upgrade therefore carry ahash_codethat no longer matches what an import computes afterwards, and left alone the next re-import closes them as absent and recreates them, detaching false positive history and risk acceptances.The page now follows the shape the 3.2 notes established:
identity_signatures_backfillbefore upgrading, because a rehash replaces the identities the backfill exists to record.manage.py dedupe --parser '...' --hash_code_onlycommands, in the same form the 2.4x and 3.2 notes use (and the command name isdedupe, matching the correction merged in docs: fix the dedupe management command in three upgrade notes #15662).Installs that never imported these scan types are unaffected, and the page says so.