digint/btrbk

Document interaction between min and non-min options

Open

#294 opened on Sep 16, 2019

View on GitHub
 (11 comments) (1 reaction) (0 assignees)Perl (2,076 stars) (136 forks)batch import
help wanted

Description

I find the documentation of the snapshot_preserve_min and target_preserv_min options a bit confusing.

First of all, the manual for those options says "regardless of how many there are", seeming to imply that there's a way to count backups/snapshots and remove the ones in excess. This doesn't seem to be possible: all retention options are time-based. Is there a way to declare "only keep the last 10 snapshots"? If so, then the _min options would make a lot more sense.

Secondly, it's not clear why there are two sets of options in the first place. Somewhere on IRC it was mentioned that the _min options are there to make sure that snapshots/backups produced during manual runs are preserved: how does this work in practice? Why would they be removed without the _min options? Presumably they would follow the same filename naming scheme, so they could be handled by snapshot_preserve/target_preserve.

Then there's the issue that if snapshot_preserve_min/target_preserve_min are set to all, that snapshot_preserve/target_preserve are effectively meaningless. This should also be documented.

Please let me know if I'm right on the above points, and I'll be happy to improve the documentation accordingly.

Contributor guide

Tech stack
None
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
needs investigation
Prerequisites
btrbk retention policybtrfs snapshotsconfiguration file syntax
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Review the current documentation for snapshot preserve min and target preserve min options in the btrbk repository, likely in the man page or README. Consult issue #190 for context on the interaction when set to 'all'. Clarify with maintainers whether the user's understanding is correct, then update the documentation to explain the time based nature, the purpose of two sets of options, and the effect of setting min options to 'all'.