Clarify versioned usage docs

[chillu]

Overview

We've described changes in how to use versioned in the upgrading guide, but it's a complex area that needs to be well supported by our docs as well. https://docs.silverstripe.org/en/4/developer_guides/model/versioning/ doesn't do this justice at the moment.

Acceptance Criteria

• As a developer I get a highlevel overview of the "cascading publish" concept
• I can decide which CMS UX I want (publish on parent, publish individually), evaluate the tradeoffs, and know how to implement them through configuration
• The documentation is structured to create an incremental understanding of the concepts, before diving too deep into API specifics (e.g. explaining ownership earlier on)
• I can easily follow on to understanding how campaigns work as an addition to versioned

Notes

• A diagram or two might help here

Pull Requests

• [x] https://github.com/silverstripe/silverstripe-framework/pull/8200

[robbieaverill]

It might be nice to clarify how recursive publishing works with unversioned parents that own versioned children. SiteConfig -> associated image is a very common example that comes up in the community Slack channel regularly - "when I save my SiteConfig my image isn't visible on the frontend"

[maxime-rainville]

Changes to apply

Restructure document

I want to reorganising the DataObject the doc around 4 main poles:

• Higher level concepts
• Interact with versioned DataObject
• Interacting with ChangeSet
• Implementing a versioned DataObject

Higher level concepts will explain what versioning does without delving on technical details. The purpose here is to give an overview of what is possible and too help developers unfamiliar with versioning understand core concepts.

The other 3 poles are more technical and mostly reuse the existing usage content.

I’ve also added an Advanced versioning topics section at the end to cover more esoteric information that goes beyond your regular use case.

Drafts some new content for key sections

Most of the existing content will be reused as-is.

I'll revise and enhance content content around:

• Cascading publish
• ChangeSet
• UX options for publishing content

Other minor changes

• Switch all headers to sentence case
• Use longer task-oriented headers
• Add an versioning 101 intro at the top

Current structure

• Versioned gridfield extension
• Database Structure
• Usage
  • Reading Versions
  • Historical Versions
  • Writing Versions and Changing Stages
  • Forcing the Current Stage
  • DataObject ownership
  • Unversioned dataobject ownership
  • DataObject ownership with custom relations
  • DataObject Ownership in HTML Content
  • Changesets, a.k.a "Campaigns"
  • Implicit vs. Explicit inclusions
  • Changeset actions
  • Changeset states
  • Change types
  • Custom SQL
  • Permissions
  • Page Specific Operations
  • Templates Variables
  • Controllers
• API Documentation

Proposed new structure

• Understanding versioning concepts
  • Stages
  • Ownership and relations between DataObject (DataObject ownership)
  • Cascading publishing
  • Grouping versioned DataObjects into a ChangeSet (aka Campaigns) (Changesets, a.k.a "Campaigns")
  • Implicit inclusion
  • Explicit inclusions
  • Permissions
• Interacting with versioned DataObjects
  • Reading latest versions by stage (Reading Versions)
  • Reading historical versions (Historical Versions)
  • Writing changes to a versioned DataObject (Writing Versions and Changing Stages)
  • Publishing and archiving a versioned DataObject (Forcing the Current Stage)
  • Deleting versions of a DataObject
• Interacting with ChangeSet
  • Adding and removing DataObjects to a change set
  • Perming actions on the ChangeSet object (Changeset actions)
  • Getting information about the state of the ChangeSet (Changeset states)
  • Getting information about items in a ChangeSet (Change types)
• Implementing a versioned DataObject
  • Applying the Versioned extension to your DataObject
  • Defining ownership between related versioned DataObjects
  • Unversioned DataObject ownership
  • DataObject ownership with custom relations
  • DataObject Ownership in HTML Content
  • Controlling how CMS users interact with versioned DataObjects (Versioned gridfield extension)
  • Controlling permissions to versioned DataObjects
• Advanced versioning topics
  • How versioned DataObjects are tracked in the database (Database Structure)
  • Writing custom queries to retrieve versioned DataObject (Custom SQL)
  • Controlling what stage is displayed in the front end (Controllers)
  • Page Specific Operations
  • Templates Variables
• API Documentation

[chillu]

That structure looks awesome, thanks @maxime-rainville.

You could argue that "Implementing a versioned DataObject" is a more common dev concern than "Interacting with versioned DataObjects", because a lot of this happens behind the scenes in SilverStripe. Maybe that section should come first?

Given the above, I'd also move "Controlling permissions to versioned DataObjects" into "Advanced Topics"

[maxime-rainville]

Good, I'll get started redrafting Monday. So we'll go with:

• Implementing a versioned DataObject
• Interacting with versioned DataObjects
• Interacting with ChangeSet

[maxime-rainville]

@chillu I'm almost done with versioning doc. I'm not quite sure about this bit:

I can decide which CMS UX I want (publish on parent, publish individually), evaluate the tradeoffs, and know how to implement them through configuration.

Maybe I'm just being blind here, but it's not quite clear to me we provide much in terms of UX customisation here.

[chillu]

Maybe I'm just being blind here, but it's not quite clear to me we provide much in terms of UX customisation here.

We at least allow you to add or remove "publish" buttons on individual GridFields, right? For example, content blocks does this to default to "page-based cascading publishing". That's typically easier to understand, but sometimes not granular enough. Those are important concerns for developers to understand, otherwise they run the risk of providing a confusing experience to their CMS authors.

[maxime-rainville]

Just finalised the PR. I went down into a bit of rabbit hole and added a part about rolling back changes and restoring archived versioned. I moved the low level methods (e.g. copyVersionFromStage) to the advanced section and tried to emphasis the high order methods (e.g. publishRecursive).

Regarding the UX customisation, the existing doc in there looks relatively simple and suitable to me. I'm not sure how much more there is to add in there.