Provide an updates list/blog

[elb98rm]

Background

This ticket is raised following a brief discussion in the json:api discussion forum

Request

JSON API needs a version changelog where the specifications changes can be found.

More information

I maintain a repo for php that supports JSON API.
With v.1.1 released recently (congrats!) I want to update my code to support the new features.
I can’t seem to see a "changes" document… While going through the spec is "fine", it’s also a huge waste of time for subtle changes, and could easily cause me to miss things. Is there an updates page? Others do this and it’s very useful.

Here is an example of how php does it:

php 8.1 released

Success criteria

• A page or resource is created where new features are shown
• These are in a separate (or are filterable) from the main spec, so that differences can be seen

[jelhan]

There is a brief summary of changes provided as update history. It's part of the about page. Not very easy to discover.

Is this what you are talking about? Or are you looking for way more detailed changelog?

[elb98rm]

I've already seen this, and I'm not sure it carries all I (and others) need. I don't know if this list is definitive/complete.

I maintain an open source repo - json-api-formatter - and in order to upgrade the code to 1.1 compliance, I'd need a list of all changes, else I have to go through the entire spec, line by line, hoping to notice differences.

As per the php8.1, I can clearly see the new features.
There is also a specific updates section.

Even if it's just a definitive list (with the detail in the spec) this would still be useful.

[jelhan]

I will go through the list once again and see if anything is missing.

If you (or anyone else upgrading libraries to v1.1) notice that anything is missing, please create an issue.

In general, v1.1 does not contain any breaking changes. It only contains additions, clarifications, and wording improvements. This may be the reason that the changelog is smaller than you expect.

[jelhan]

I noticed that there is additional context on the motivation behind this request in the forum thread:

It says “New features include”. This implies to me that it is not all changes, just interesting ones.

I interpret that the fear that other breaking changes may be missing in that list. Copying my reply from the forum here as well:

v1.1 does not include any breaking changes.

It includes some additional clarifications and improvements in wording. Such changes could be shipped any time even to a version, which has been published already. We have done it a lot over v1.0 lifecycle.

From an implementation perspective only the new features should be relevant. Unless there is a bug in the implementation caused by unclear wording of the specification previously. But that would not be related to v1.1 release.

Does that resolve the need for a more detailed update list?

[elb98rm]

No. It's not the fear for breaking changes.
It's the fear that my software will become more and more feature incomplete over time simply because I can't track updates reliably.

[jelhan]

It's the fear that my software will become more and more feature incomplete over time simply because I can't track updates reliably.

The updates list in history covers all new features.

Also I wouldn't be too afraid that you miss important features. I'm sure that consumers of your library will request support for those features if they need them. 😉

[elb98rm]

Your use of language is "... a brief summary of changes...". To me that implies an overview/summary.. which does not contain detail and would omit items.

Are you confirming that this a complete list (even if not detailed)?

The ambiguity would be changed by changing the text to say: "a brief summary of all changes".

Regarding users - sure, but it could also cause a person to ignore the software in the first place: this would be invisible to me. Not everyone wants to contribute like us! :)

[elb98rm]

(and to be clear: if it is all changes, that is completely satisfactory!)

[auvipy]

The updates list in history covers all new features.

Usually new versions should come with post with what the new changes will let the users do, and what problem it is going to address over the older version.