Typographic updates

[robredpath]

No description provided.

[stevieflow]

This was raised in #477

[stevieflow]

If.. this PR were to be a PATCH update - then should / could we follow our own (but new) guidance on branch naming: https://os4d.opendataservices.coop/patterns/versioning.html#version-management ?

@duncandewhurst & @kathryn-ods may be able to advise (non binding - as we can also treat this PR as a test!)

[duncandewhurst]

Happy to advise on what would be involved in adopting the version management approach documented in OS4D. Is the approach currently used in IATI documented anywhere?

[robredpath]

The versioning guidance in OS4D seems to presuppose that only one upgrade proposal is in play at once. That's appropriate for standards like OCDS where the rate of change is very small, but the trend for IATI seems to be towards a period of more active updates - indeed, the Standard Gazette template has four categories, each of which can be a list!

I'm wary of putting more meaningful information into more places than we already have, so if we are going to adopt a branch naming convention (which is probably a good idea), I would suggest that we create one that is fairly meaningless. For example, we might name branches with the title of the related proposal, which would aid cross-referencing.

[stevieflow]

Thanks @duncandewhurst @robredpath

@duncandewhurst the only info we have is here: https://iatistandard.org/en/iati-standard/upgrades/how-we-manage-the-standard/upgrade-process/ - which is not too helpful, as we are not at 3.0.0!

@robredpath yes, good point. I can certainly see that on previous evidence. We may choose not to be so multi-threaded going forward, to make things easier to follow. As you indicate, there is a assumption that a proposal includes a PR - we may also see that there might be a legitimate need for a gap in time between the two.

[duncandewhurst]

The versioning guidance in OS4D seems to presuppose that only one upgrade proposal is in play at once.

To clarify, the -dev branches are for staging releases, and feature or topic branches should branch off those. There can be many feature or topic branches for each -dev branch. For the forthcoming OCDS 1.2 release, we've merged nearly 250 feature branches into 1.2-dev.

You can group changes/issues into feature or topic branches in whatever way makes sense.

Once all the feature or topic branches for a release are reviewed and merged into the -dev branch, then the governance process can be followed (peer review etc.) and once complete, the -dev branch can be merged into the 'live' branch in order to release the new version.

So, assuming semantic versioning, you might have the following staging and feature branches in IATI, for example:

• 2.0-dev for staging non-normative changes to the current version of IATI, i.e. changes that don't require a new release of the standard. You can't commit directly to this branch
  • theme-update (a feature or topic branch) branching off 2.0-dev.
  • [more feature or topic branches]
• 2.1-dev for staging the next minor release of IATI, i.e. backwards compatible normative changes. You can't commit directly to this branch.
  • add-organisation-type-codes (a feature or topic branch) branching off 2.1-dev
  • [more feature or topic branches]
• 3.0-dev for staging the next major release of IATI, i.e. non-backwards compatible normative changes. You can't commit directly to this branch.
  • rename-fields (a feature or topic branch) branching off 3.0-dev
  • [more feature or topic branches]

Of course, you probably don't have all of those -dev branches at once, since you probably aren't concurrently working on versions 2.0, 2.1 and 3.0.

FWIW, when naming feature or topic branches, I tend to use the following pattern {issue #}-{topic}, e.g. 223-theme-update as it makes it easier to check out the right work-in-progress branch when returning to an issue, without needing to remember what you decided to name the branch. Of course, it falls down a bit when a branch addresses multiple issues, but it's generally a time saver.