Retention¶

viur-revision ships with a PeriodicTask (cleanup_revisions) that runs once a day and thins the revision history per origin entity. Without it, the revision tables would grow unbounded.

Bucket policy¶

Age of revision	Retention
< 24 hours	keep all
1 day – 7 days	keep latest per hour slot
7 days – 30 days	keep latest per day slot
> 30 days	keep latest per week slot

Within each bucket the revision with the most recent revision_date wins; the rest are deleted. The task processes one origin at a time so memory stays predictable.

Why these buckets?¶

Most "what changed and when" questions get more recent. Closer to the present you want fine resolution (the auto-save burst from earlier today), further back you only need a representative snapshot.

If you need a different cadence for a specific module, override cleanup_revisions and reuse the helpers:

class Example(RevisionModule, List):

    @PeriodicTask(datetime.timedelta(hours=6))
    def cleanup_revisions(self):
        # custom cadence — defer to default thinning
        return self._run_cleanup_revisions()

Manual trigger¶

The daily task can be invoked on demand by hitting cleanup_revisions_now from a browser or curl:

curl https://app.example/example/cleanup_revisions_now

The endpoint returns a diagnostic payload listing every revision processed, which bucket it fell into, and whether it was kept or deleted — useful when debugging the policy.

Edge cases¶

Revisions without revision_date (e.g. data imported from elsewhere) are always kept.
Revisions whose date arithmetic throws (e.g. naive datetimes mixed with aware ones) are kept and the error is recorded in the diagnostic output.
Single-revision origins are never touched.