Provide an updates list/blog about json-api

[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.

[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]

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 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?

[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.