As a user, I have comprehensive docs on mirroring, sync modes, and how they interact together
The "mirroring" docs page is currently empty. We need to fill this out with descriptions of what "mirror=True" and "mirror=False" do, and what the default sync mode is. This needs to be well explained to users, with particular emphasis given to the fact that a mirror=True sync on top of a repository with multiple different types of content will be extremely destructive, because mirror syncs don't respect content type boundaries.
This extends also to the interactions between immediate mode and lazy sync modes, and additive sync. There are "gotchas", like if you first perform a lazy sync and then perform an immediate, additive sync, no artifacts will be downloaded or associated with the existing content units. This is because there are no "new" units and whether the artifacts for the existing units exist or not is not checked.
#7 Updated by email@example.com about 1 year ago
The responsibility of documenting this feature, IMO belongs to the plugins. This isn't necessarily obvious, because the field is implemented by pulpcore, and used by pulpcore-plugin in the declarative version, but plugins are not required to use the sync serializer and declarative version. It is conceivable that some plugins may not use this feature, or that it might behave differently. Fortunately, plugins do not need to do much, since this is a REST API field, if it is used, it is automatically included in the plugin REST documentation.
IMO, I don't think this needs a prose section. Instead, this story should be to remove the stub and improve the help text. Suggestion:
If True, remove content that has been removed upstream. If False, the sync will be only additive.
Please register to edit this issue