Update the guidance on change history

[yolile]

Closes #1412

[yolile]

Thank you, @duncandewhurst, for the changes. I think this is ready for James to review again, right?
And should we add a link to the new page from the Determine data needs section? (particularly to the "Whether to publish a change history" item)

[jpmckinney]

And should we add a link to the new page from the Determine data needs section? (particularly to the "Whether to publish a change history" item)

Yes!

[jpmckinney]

I rewrote change_history_options per the discussion here: #1531 (comment)

That page now uses "full updates" to mean "full updates in the context of a change history" – in contrast to incremental updates. It also uses "individual releases" to mean "individual releases, when you can't publish a change history" – in contrast to "compiled releases".

However, that usage is inconsistent with the other pages.

I suggest renaming the other pages:

• Incremental updates -> Change history. As Duncan commented, the examples are a mix of full and incremental updates. In any case, we don't have a page for each of these (and I don't think we need one, as the distinction is fairly minor).
• Full updates -> Individual releases with no change history
• No change history -> Compiled releases with no change history

To be clear, if a publisher follows the 'easy releases' approach, then they aren't publishing a change history (at best, a third-party can reconstruct a change history).

There might need to be some corresponding changes to the introductory paragraphs on those other pages.

[duncandewhurst]

@yolile, @jpmckinney are you happy for me to pick up and complete this PR?

[yolile]

@duncandewhurst Yes, I'm!

[duncandewhurst]

To-do:

• Review built version of documentation
• Check guidance on setting .date in guidance on hashing (no last modified date)
• Cherry pick updates to amendments example and update JSON directives in example 3

[duncandewhurst]

@jpmckinney this is ready for your review. I've made the changes suggested in your last comment, simplified the examples in line with our discussions elsewhere, and made various copy edits for consistency and clarity.

Two things to flag:

1. The old easy releases guidance describes how to use a hash function to update release id in the absence of a last modified date. However, it doesn't explain how to set date. In the new individual releases guidance, I've recommended setting date to the date the release was generated (i.e. the date the user downloaded the data). Happy to discuss if there might be a better approach.
2. In the individual releases guidance, I've preserved the recommendation to prefix .id with the ocid so that users don't need to filter on ocid to find releases belonging to the same contracting process. However, I'm inclined to remove that recommendation so that the examples align with the rule that .id need only be unique within the scope of the contracting process. It seems like more work to filter on part of a field (.id) than on a separate field. What do you think?

Edit: I forgot to mention, this PR includes some commits from #1661 which is also awaiting review. Whichever is reviewed first, I'll make the necessary updates to the other one.

[jpmckinney]

In the individual releases guidance, I've preserved the recommendation to prefix .id with the ocid so that users don't need to filter on ocid to find releases belonging to the same contracting process. However, I'm inclined to remove that recommendation so that the examples align with the rule that .id need only be unique within the scope of the contracting process. It seems like more work to filter on part of a field (.id) than on a separate field. What do you think?

Agree - I prefer your suggested simplification.

[duncandewhurst]

Great. I've done that in c848382

[jpmckinney]

Noting that amendments.md includes changes from #1661, but my suggested edits in that PR don't overlap, so there shouldn't be a merge conflict. amendments.md has an extra commits in this PR, which can be reviewed independently:

• 3c64c95#diff-d3ab3df28ed0eba11bf5bcc05a619b2e8048d802f73ce950116f800fba79dd6d (small)
• 104d2a4#diff-d3ab3df28ed0eba11bf5bcc05a619b2e8048d802f73ce950116f800fba79dd6d (merge)
• 0cc23e1#diff-d3ab3df28ed0eba11bf5bcc05a619b2e8048d802f73ce950116f800fba79dd6d
• 6f51570#diff-d3ab3df28ed0eba11bf5bcc05a619b2e8048d802f73ce950116f800fba79dd6d