Rename globally: References -> Relations

[stanislaw]

...and preserve the existing behavior for some time.

[stanislaw]

A large chunk of this work has been done in:

• https://github.com/strictdoc-project/strictdoc/issues/1310
• https://github.com/strictdoc-project/strictdoc/pull/1342
• https://github.com/strictdoc-project/strictdoc/pull/1339
• https://github.com/strictdoc-project/strictdoc/pull/1336

[stanislaw]

After a few months, deprecate REFS and completely switch to RELATIONS.

[richardbarlow]

We're just updating to v0.0.46 in our workflow and have seen that we need to perform the REFS->RELATIONS change and move the RELATIONS field to be the last. This was very easy to do using strictdoc passthrough.

However, it seems that when this change was implemented in strictdoc it re-introduced the concept of a 'warning' that was eliminated in https://github.com/strictdoc-project/strictdoc/issues/451. If there is a desire to have a separate concept of warnings then once again it would be helpful to be able to treat them as errors and exit with a non-zero exit code so that we can ensure that we have no warnings present.

[stanislaw]

Hi, thanks for asking! This case with a deprecation warning is a little special because I wanted to avoid breaking things right away. I know of at least two users who would prefer to not have things break suddenly.

The fact that you noticed the changes and migrated was pretty much what I was aiming for.

This was very easy to do using strictdoc passthrough.

It is good to know that this workflow has worked well for you.

The plan was to let the old REFS work for 3-6 months and then remove the old behavior for good. Along the way, I was planning to notify a few people who I know could be affected, including you. One thing connected to this is that I am currently missing a communication channel which I could use to notify as many existing users as possible. Only some users are in Discord, some users only use emails, some users are here on GitHub. Given this situation, the best thing would probably be to introduce a blog and a mailing list newsletter at the same time but I am not there yet with setting all of that up.

[richardbarlow]

Thanks for the explanation. Personally I would expect to find information relation to deprecation of features and breaking changes in the changelog/release notes for the project. The critical thing is that the items written in the changelog/release notes are written for the intended user (i.e. a person looking to update the software) and are not just a dump of all of the commit messages or issues closed. Ideally breaking changes (or upcoming breaking changes) would be clearly highlighted.

An example of the release notes for a piece of software that we use and regularly update (with help from the release notes) can be found here: https://docs.zephyrproject.org/latest/releases/release-notes-3.4.html. The changes are written up in a manner that is meaningful for a person updating the software, grouped together to allow whole sections to be skipped if they are irrelevant and the sections are approximately ordered by importance.

For a project like strictdoc (at its current scale and rate of development) I would expect the release notes to be quite short and, if desired, a full list of commit messages and issues can still be included after the more hand-crafted sections. It would also be great if the body text in the GitHub Release record was the same as the contents of the CHANGELOG.md file for that release (this may open up the option of automatically inserting the Release record body from the CHANGELOG.md section).