As part of consolidating the Technical Core and further improving our software management processes, the IATI Technical Team has formalised and published new documentation on the following processes:
We thank our Governing Board technical focal points for their input, especially on the deprecation process. Let us know if you have any questions by posting below or emailing support@iatistandard.org
Thanks for sharing this - I think it's very useful to have a process to refer to.
Depending on the size or importance of the software, I think it would make sense to have an initial step of consultation with users *before* deciding to deprecate the software. As the article linked to in one of the documents above states:
> "feature deprecation and application sunsetting can have profoundly negative effects on the users who rely on those capabilities"
I think consulting with users would help to clarify whether the negative effects / costs to users outweigh the potential benefits from deprecation.
I think it might also make sense to adjust the deprecation and removal timescales depending on how important the software is, or how much it's being used. A total of 1 year before removal seems fairly reasonable, but e.g. for deprecating the IATI Datastore, if a number of users are relying on this service and integrating with their systems, you might want to extend this period to something around 2 years. Whereas for other much smaller tools, you could probably reduce that time.
Thanks for this - very helpful and interesting
I spoke with colleagues who work on other open data standards and software (eg Open Contracting; Beneficial Ownership Data Standard). One thing that might be of use here is the open contracting software roadmap principles: https://ocp-software-handbook.readthedocs.io/en/latest/roadmap/index.ht…
Regarding:
> If a change requires us to consult with the external community, it is a Major Version
Our sense here was that this seems to be back-to-front. We think what is intended is:
- If it is a Major change, then we are required to consult with the external community.
Right now, it could be read that *any* form of consultation would automatically mean a Major version - which ignores the scope and change of the work involved. Hence, if the three bullet-points below the table in https://iatistandard.org/en/guidance/developer/software-versioning/ were reversed in their conditionality, then it would help determine how communication channels are informed by the software changes that determine versioning.
Apologies if that's in the weeds, but this is why we do this!
Thank you for the feedback, this is a good point and we will look at modifying the language here to make it more clear.
Agree. And I would like to add that communication about patches can be very useful as well, e.g. when the patch solves a bug which causes problems for users. In that case I would like to be informed.
Thank you for the feedback. Information about patches is made available in GitHub under the release notes (e.g. https://github.com/IATI/datastore-search/releases/tag/v1.2.0) and may be included in more formal communication where we think it's useful (like the example you provide). However, making a requirement that all patches (e.g. minor dependency updates) be externally communicated we feel would create undue noise in our communications for the typical user.
Understand what you are saying, but feedback can also be implemented light weight by simply adding the link to github you mentioned above in the IATI newsletter or technical newsletter under "New releases". That is also good to highlight the hard work you have been doing to keep everything up and running.
Herman van Loon IATI Technical Team I think we risk going around in circles by trying to pin down the exact level of detail required for communications. It seems easier to distinguish between two things:
- Documentation: we'd all expect that any change, no matter its scope, has the relevant level of documentation available. From a GitHub issue / PR, through to more in-depth documents - the level of detail will set the documentation needs
- Communication: this is about how this documentation is signalled to stakeholders. Agreed that a long list of PATCHES may not be appropriate for a general IATI newsletter - but that isn't the only channel available to the initiative.
Taken together, we can solidify accountability and credibility (for all) by documenting and communicating the sterling efforts being made.
I think citing "the typical user" isn't helpful, as this isn't explicitly defined, and the small world of IATI has many atypical users! Just make sure any changes are documented and communicated in relevant and appropriate ways. One size, just doesn't fit all.
Fully agree with Mark Brough . Especially because of the principle stated in the article "Software deprecation is all about continuity. You must ensure that developers don't alienate the customer base and instead help them through impending product changes."
Thank you for your feedback, hopefully we can clarify on these points.
1. Consultation - The deprecation process as defined in the policy starts with an "Identification" step, which is then followed by a "Community Research" step which can include consultation with the community based on the context. The outcome of this step may be to not deprecate the software.
2. Timescales - Agreed, the process as defined in the policy specifically does not set a fixed timescale for the deprecation and it is left to judgement based on the Community Research and Planning steps.