Provide guidance to document authors on updating the "tooling" submodule in their document repo

[thomasheritage]

• When should this be updated (if ever)? e.g. just before final publication so that the latest code is used for the final render?
• What are the instructions for making the update? -- including:
  • git submodule commands + committing the submodule change in the doc repo
  • copying "tooling/.github/workflows/main.yml" to ".github/workflows/main.yml" [actually it would be good to explain this duplication in the html-pub documentation regardless]
  • dealing with any new validation errors

Related to #159

[SteveLLamb]

Agreed, to this point it's been don't change it unless you NEED to. But we have been making loads of required updates.

[thomasheritage]

Also, it's useful to note (and provide advice on dealing with) the fact that updating the "tooling" version used on a branch is likely to create a merge conflict with the main branch... (so you probably want to update the "tooling" version on main at the same time)

[thomasheritage]

you probably want to update the "tooling" version on main at the same time

In fact, it's important to update "tooling" on main before updating "tooling" on the development branch otherwise there's a merge conflict and the document render on the development branch is skipped -- but the commit still gets a green tick like below (which is rather misleading...)

[SteveLLamb]

A submodule pointer is just a committed SHA, so a bump on a branch merges into main the same as any other commit. A conflict would only arise if main also bumped to a different commit in parallel, which is the same as any normal merge conflict and not specific to submodules.