Extra information in the release notes

[TacheI]

The recent addition of info in relation to changes, such as API calendar, is much appreciated.
More information would be needed in the release notes to help participants assess the impact faster and prevent detective work in between the current and past standard spec, the maintenance iteration document and other decision approvals, future dated obligations and the API release calendar.
My suggestions are that the release notes:

• include in the individual lines the issue number and link to it. For example that the first change under APIs in release 1.15 relates to issue 430. In release 1.15 there have been 21 issues implements. It is a huge detective work to piece all the issues to the changes in the release notes.
• include another column that states for each line which industry is impacted and if it impacts the data recipient or the data holders or both. This will help understand the impact faster.
• introduce a new column that states the date the change is expected to be introduced by data holders and data recipients. This will prevent the detective work to match the changes in the release notes to the dates in the future dated obligations
• Specify clearly which API the change refers to and which field in the API. This prevents more detective work to figure out which API is affected (if the field is specified) or which field is affected if the API is specified. For example in release 1.15, the 2nd row under APIs states 'Get Account Detail v2: Changes to accomodate lending products without an instalment date or repayment frequency'. Would be very helpful to state the actual fields impacted. Another example. In row 3 under APIs in release 1.15 states 'Corrected GetDataHolderBrands registerUType and jwksEndpoint schema definitions to clarify their usage in DH to ADR client authentication'. It would be very helpful if the description states the API impacted. For someone who is not working with this particular spec every day it is time consuming to figure out the exact impact.
• provide for each change detailed information about the past behavior and newly introduced behavior. For the example above 'Corrected GetDataHolderBrands registerUType and jwksEndpoint schema definitions to clarify their usage in DH to ADR client authentication' would be very helpful to state what the past definition was and what the new definition is. As it stands I have to put the old and new spec together and find out the differences.
  Thank you!

[CDR-API-Stream]

Hi @TacheI,

There are four documentation enhancements targeted for release in v1.17.0. This is in conjunction with the supported DP237 changes. They have been staged as proof of concepts for review and comment.

• Proof of concept: obligation highlighting
• Proof of concept: obligation milestone windows
• Proof of concept: navigation for diffs and code examples
• Release notes shall include the change request referenced (see here). A summary of the CRs that have been addressed in the release are also provided (see here).

[nils-work]

As part of a backlog review in Maintenance Iteration 21, it was suggested that this issue could be closed.
If there are no further comments, this issue will be closed on 25 October 2024.