Notification of removal of misleading section from the Developer's Reference site

Notifications
#1

Introduction

This post notifies you on an update to a section of the developer reference that is currently misleading.

In http://reference.iatistandard.org/203/developer/ssot/proposal/#tags we offer an option to retrieve a specific version of the standard using Git tags (https://git-scm.com/book/en/v2/Git-Basics-Tagging).

While this is technically correct, it’s currently misleading for various reasons:

  • the currently tagged snapshots of the repositories are out of date, as shown in the screenshots below:

pMoOcTFJ_5WDpZajBf048gn55pNH3Lr5i61oknZXzNTtFEmU2tD3oB6CDARBKzICZek0p6nOjjjqF7T6utat8Vt4Z26gWIzjMEqbYaLHwOEZwsmdusg__w6Lu3FxT9FNNqV0zDwX.png774×968 39.2 KB
SAK1ol1iZsotrzQR29gAH8naVxEqlWAZEl_x7P1cWlr8iE3KUT1rYECuWdlM4KM4esU9e2ZAvwDSAqWMZDM6tQWo9n4IE5PHKHrNH2iDIN3c89DYIrpvCLQDpePuMNYEdTpZi4Zu.png742×972 41.5 KB
fYDz8rE7pt4LQ6kARyA92WHwjg57GccxmjgoSKW0kpHZkW0bP0JPhrChnyGHim6Fdx9UeK1wQEbnZVEZ-kLbwHYh17-KQQGB2SAD22n9hHpZCV7jNbR6ig3Xs8tSDzx9oSWXALa3.png704×678 25.4 KB
SZliXHo_Sn0icDoUqehJTciFmSQ0t59Mj-1f5J6z49soqaSO0wqL82LnxbgZd7bUn7XYN-qKkKG2ARov0dMHqQf82fO8e5tPq57VFy2D46EeiHExAaEgf6JuBqQZihr6vLbgW044.png762×996 39.6 KB
HciLpcK-om3XmhM1_gSYtRPr9sT1svl-VXU6cs15ALfTzMwlZvWH57T3vltQjmBl09Er4bcDSDnbSONVcbYrQHsGsUsS-a9EmE942-VFJcGTe3UEgwWQeqWlzGB-p0ZmbcQrQJ0l.png708×1444 61.8 KB
CKNjoYZHh5V4OR2LoY6XlSN8CH5nco4SEmLeJrQtTEFq8Wbs4AW74xrkvrfO0BCLdOAfXbxR1YyfO8hsoinVlA0IGiYuxrxfjEynusVsXToenbeAQzNRCDZ1X8QuxDK9_81kHzbb.png700×1018 40.5 KB

  • the Standard uses a MAJOR.MINOR versioning system, from which the tagged branches can easily diverge as soon as a new bugfix is introduced after a tagged release; as an example, version 2.03 of the Standard isn’t due to change any time soon, but if a developer modifies one of the files within the SSOT, the tag becomes obsolete.

Tagged branches will make sense once Semantic Versioning (“semver” https://semver.org/) is introduced for the Standard (as suggested in https://iatistandard.org/documents/242/Paper-10-Proposed-revisions-to-the-IATI-Standard-upgrade-process.pdf) and the Standard version will then acquire the form of MAJOR.MINOR.PATCH, allowing the developers to always fetch the most recent version of the codebase (and thus the Standard itself) without ambiguity or confusion.

Relevant GitHub issue: https://github.com/IATI/IATI-Standard-SSOT/issues/153

Possible options

  • Removal of tags from branches + update of the reference page till semver is introduced for the Standard

  • Manual upgrade of tags “every so often”: albeit this not being a bad option, it requires the developers to constantly remember to remove a tag (in Git, a tag is not reusable unless deleted) and re-tag a branch once a bug fix/code patch happens. This isn’t a stable approach and introduces the risk of leaving a branch’s tag out of date anyway.

  • Introducing the PATCH number in Git tags (and not in the Standard): this would cause, in our opinion, a potentially confusing mismatch of versions (eg: Standard version 2.03 vs. Git-tagged branch version 2.03.64 would both refer to version 2.03 of the Standard)

Recommendation: Temporary Deprecation

Our suggestion is to temporarily remove the tags from the affected repositories and updating the reference guide with the complete removal of the tags guideline. The developers wanting to work on the Standard will still be able to retrieve it using the named branches (as described in http://reference.iatistandard.org/203/developer/ssot/proposal/#ssot-branches) and always be sure to correctly fetch the latest version.

This change will not impact anybody and is going to provide a tidier and non-misleading documentation page.

We aim to push this update before the 10th of November 2018.

2 Likes