Understanding impact when considering changes to the standard

[stevieflow]

We talked in the last meeting in terms being clear about understanding and discussing the potential impact of any change to the standard, whether that be to publishers, data users, maintainers of tools, providers of services or any other stakeholder

Indeed, with our shared examples from 360Giving and Open Referral, there's an in-depth consideration of impact

Taking this forward, we've drafted a set of considerations around making impact-based assessments on changes to the standard, that could then help us then further refine what type of change (minor, major, patch) they might eventually be.

Thanks to @rhiaro for this welcome input, especially as it brings in experience from the W3C Technical Architecture Group they are a member of.

[IsabelBirds]

Draft: Impact-based upgrades for the IATI standard

Thanks to @rhiaro for their work on this.

---

Impact-based upgrades

Different types of change to the standard have different impacts (positive and negative) on different audiences.

The goal of impact-based upgrades is to enable forward-momentum and innovation so that the standard continues to be useful and relevant, and so that we can learn from our experiences to continually improve the standard for everyone, while remaining sensitive to the needs of those who maintain software and systems to publish and consume data.

Types of change

The process followed for a change depends on the practical impact of the change on users and publishers of IATI data, rather than the contents of the change and its impact on the version number.

Editorial changes (non-normative): fixing spelling mistakes; improving clarity of descriptions; resolving wording ambiguities to align with common practice or/and original intent (as appropriate) where this does not substantively change the use of the field in practice; ‘common sense’ improvements to make the standard easier to understand.

Alignment changes (normative): updating fields to align with how they are used in practice; deprecating/removing unused fields; ‘common sense’ experience-based improvements to make the standard easier to use.

Development changes (normative): backward-compatible; adding new optional fields; deprecating little-used or problematic fields.

Mixed Impact changes (normative): non-backward-compatible changes which have clear benefits but where a significant minority or a specific known set of data users are impacted; resolving ambiguity where there is not clear consensus or common practice for the resolution.

Substantive changes (normative): removing features that are widely used; non-backward-compatible changes to features that are widely used; changes to structure.

Implementing changes

Type of change	Authority	Process
Editorial	Secretariat*	Suggested changes are publicly logged in github issues; changes are batched and released on a regular (predictable, documented, broadcast) cycle.
Alignment	Secretariat*	Consultation with data publishers and data use communities about concrete change proposals with a period for questions and feedback; fixed release date for the changes; review period during which the change can be reverted.
Development	Secretariat + Board	Proposed changes are incubated by implementers; when two or more independent implementations are demonstrated and there are no unaddressed substantive concerns, a change proposal goes to the Board to sign off.
Mixed Impact	Secretariat + Board	Consultation with the community to determine pros and cons and a realistic timeline; when two or more independent implementations are demonstrated and there are no unaddressed substantive concerns, a change proposal goes to the Board to sign off.
Substantive	Members	Consultation with the community for feedback and refinement of proposal; incubation of proposed changes by implementers; change proposal is agreed by Members.

* Where the Secretariat has authority to make changes, all changes are considered and reviewed by at least two members of the team before being included for release.

Initiating a change

Any member of the community can propose or request a change (or note a problem that could be solved by a change) by raising an issue on github, or contacting the IATI Support Team directly who can raise an issue on their behalf.

The Secretariat is responsible for triaging issues, determining the type of change needed, and setting a timeline depending on the time and level of consultation needed to carry it out.

Or

The Secretariat is responsible for coordinating a regular, open working group which triages issues, determines the type of change needed, and sets timelines depending on the time and level of consultation needed to carry it out.

Discussion of proposed changes is carried out in github issues and on scheduled community calls which are planned and publicised in advance.

Recording and publishing changes

Proposed changes are published in a regular gazette. Any IATI Member may raise an objection to a particular change and either request changes or seek wider oversight of the change. All objections must be registered within 45 days of the proposed change being published.

All changes are recorded in a public changelog, and the version of the standard updated appropriately.

Development, Mixed Impact, and Substantive changes are publicised to the community through appropriate channels depending on the likely impact of the change.

Versioning

In order to effectively communicate the current version of the IATI Standard, each update increments the version number according to Semantic Versioning (semver) (major, minor or patch) depending on the content of the change.