Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add docs for the deletion of incremental backups #987

Merged
merged 1 commit into from
Aug 20, 2024
Merged

Add docs for the deletion of incremental backups #987

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions doc/manual/43-backup-commands.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,11 @@ barman delete <server_name> <backup_id>

The `delete` command accepts any [shortcut](#backup-id-shortcuts) to identify backups.

> **IMPORTANT:**
> If the specified backup has dependent block-level incremental backups,
> those backups and all their dependents will also be deleted during this operation
> as they would effectively become unusable for recovery with a missing parent in its chain.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check the parts where there are NOTES in this doc file. It would be good to keep standards with notes, like below:

A note with capitalized letters starting with a > symbol and bold.
Example:

NOTE:

Also maybe a reword like the following:
if the specified backup is a postgres backup and has dependent incremental backups, this backup and all their following dependents will be deleted. This happens because a backup without its parent makes the backup chain invalid and a further recovery of any of the dependent backups would not be possible.
This only applies to backups with backup_method="postgres".

My thought is that we should be less wordy and try to use the same words like dependent OR descendant (not both). Also i think that part (i.e., backups taken with --incremental <backup_to_delete>) is not so important and might be confusing.

The reword is just a suggestion, you do not need to follow it!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, tbh i don't like this part either "(i.e., backups taken with --incremental <backup_to_delete>)" hahahaha.

I have two points about this:

1 - Do you think the term "postgres backup" is well-understood by the users? I mean, at the end, everything is a postgres backup, right? I've been avoiding this as I think it is mostly used by us to differentiate it from rsync backups but i'm not sure if it is the correct term.

2 - I have the impression that notes are mostly used when you're explaining something "extra", like something that didn't fit in the context but that's still important to mention. In this case, i think explaining this behavior is just a continuation of the existing explanation. What do you think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 - good point! If this is misleading to users, we might need to use backup_method="postgres" instead of just "postgres backup". Something like this!
2 - Yeah, i guess i saw the Note in the beginning of the sentence and i thought it would be better to put as a big NOTE. But i guess that explanation could be an IMPORTANT flag or NOTE because in fact it is some kind of note or important information.

But of course, we can wait for more suggestion from the others!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I'll try a better version later today and ping you here to see what you think.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

when adding a NOTE or an IMPORTANT section to the doc, use

**NOTE:**

or

**IMPORTANT:**

Not commenting on the content yet as seems that some changes are going to happen @gustabowill

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@andremagui @gcalacoci changed it and added it as important note. I'm using the term "block-level incremental backups" instead of "Postgres incremental backups" as I think is clearer and is also what I'm using to explain the --incremental option in the other doc PR.

## `keep`

If you have a backup which you wish to keep beyond the retention policy of
Expand Down
Loading