Skip to content

Breaking changes

Jump to bottom
Chris Millar edited this page Jan 17, 2024 · 2 revisions

There are times when a "breaking change" is required. This would mean that content re-authoring is needed due to requirements changing or new details emerging. Breaking changes should be avoided to the largest degree possible, but sometimes they are un-avoidable.

Discussion

All avenues should be explored and discussed between the affected teams (engineering, gwp, seo, etc.). It's important to get an approved and agreed upon path forward before making any changes that could break existing content. It cannot be overstated how expensive content changes in SharePoint are. There simply isn't good standardized tooling (yet) to do any sort of bulk changes to content.

Breadth of changes required

Due to the reach of Milo content, teams will need to identify what content is impacted by the breaking change. This can be as simple as asking in Slack, using RUM data to see if a block is being used on live pages, or doing searches for content in SharePoint.

Mitigation

There's not always a clear cut way to solve a potentially breaking change, but here are some considerations:

  1. Can the potentially breaking change be implemented in a way that, while not ideal, does not require re-authoring? Let's say you have a feature that requires on / off. 1,000 documents get made and it's realized that there needs to be more context than on/off... subset of pages, etc. Can you implement another flag, while not ideal, to live in tandem of the on/off feature?
  2. Can the feature be transpiled at runtime? This is great for things like block renames. In a project's scripts or utils, you can pre-transpile content to be in the final shape for Milo to act.

Expectations

Whoever proposes and implements the breaking change should also implement the migration of content (formerly Sling Pipes). The engineer will need to work with GWP leadership to determine the migration plan. This can include staging content for validation as well as bulk preview & publish.

Tooling

The Milo Core / AX team can provide guidance and tools based on past implementations. The gist is basically:

  1. Convert Word to MD
  2. Convert MD to MDAST
  3. Make content changes
  4. Convert MD back to Word
  5. Validate Word docs [1]
  6. Upload Word docs to drafts for GWP validation and approval
  7. Make backup of live content
  8. Replace live content with updated content

[1] This process can often create corrupt Word documents.

Clone this wiki locally