What about this one? https://pagure.io/waiverdb/issue/111
I was on PTO when it got merged (https://pagure.io/waiverdb/pull-request/203), but I don't think it was released.
I'll close the issue BTW.

What about this one? https://pagure.io/waiverdb/issue/111

Oops, missed that one. Added.

:+1:

I guess you can just call it WaiverDB 0.11... Is the idea that you would then later fill in the version when you tag the release? Our script is not currently smart enough to do that.

It would be nice to say why we have the new one, and what it does better. (Namely: it allows posting an arbitrary set of filter criteria, instead of the complicated and limited API we had before.)

We definitely need to write more about this one. We could make people click through to the issue and read all the old comments in order to understand, but that's not very nice.

Most important piece of information to convey is how to adjust to the new changes.

Second most important piece of information is why we are changing things.

Third most imprtant piece of information is to point out that we have kept backwards compatibility so people don't need to jump and immediately adjust to the changes -- but there are limitations on the backwards compatibility which we also need to note.

A tiny bit more detail here wouldn't hurt.

The :program:`waiverdb-cli` utility will now guess a suitable default value for the
:option:`--product-version` option in many common cases, in order to make it easier to
submit waivers. Automated scripts should prefer to explicitly pass :option:`--product-version`
in case the guessing logic does not work in all cases.

IBM Style Guide says to introduce cross-references with a phrase like "see" or "refer to". It makes the sentence flow a bit more naturally. Here it would be:

(see :ref:`client-conf`).

What user documentation did we add? I can't remember and even the linked issue does not actually say what we added either. :-)

I guess it was this doc, right? https://docs.pagure.org/waiverdb/user-guide.html

Can we link to that then? And say what it actually is? "The documentation now includes a section describing how end users can submit waivers using the command-line interface."

The wording on this entry might be a bit confusing. It can help to describe bug fixes as "previously it did this bad thing, now it does this other thing instead". How about:

Previously, when you requested a list of waivers, WaiverDB would consider waivers
from unrelated users and product versions to obsolete each other. The API now correctly
returns the most recent waiver from each user, and for each product version.

The same title is used in greenwave (added by @ralph). I like this better since using an unreleased version can be misleading.

I can fix the tag-release.sh to update the file (or check for current version).

Nice. Didn't know about :program: and :option:. Though sphinx gives me following warning.

WARNING: unknown option: --product-version

@dcallagh Thanks for the detailed input!

I addressed most comments except writing detailed info about the subject_type and subject_identifier. I'll try to pull all the information from the discussion on the issue.

Writing release notes is hard! It would help if it's updated more often and by the author of the particular change.

Yes :program: and :option: will make nice hyperlinks to the relevant man page but it requires us to have marked up the corresponding man page correctly.

Yes writing good release notes is hard, I agree! And I am super picky about them too. But it's for good reason... I have been on the consuming end of bad release notes far too often in my life :-P

And yes, if that is a subtle dig at me that I should be writing the release notes for the features that I implemented... that's fair :-) and I probably should. I can have a crack at drafting an entry for the subject_type stuff later today.

BTW, here is interesting example on how to do very detailed release notes: https://code.visualstudio.com/updates/

Also, every time vscode is updated, release notes are shown in the application. It could be very useful, but since the development and realeses are going so fast, it's difficult to go through all the changes.

Yeah the VS Code release notes are great. They obviously sink a lot of time and effort into them but I think users appreciate it. The release notes are very long but they always put the most important ones at the top.

I don't think we need to go to the same extreme as VS Code here :-) but it is always important to write these from the user's (or admin's) point of view. What does a person who consumes the software and is not deeply involved in its development need to know about this new release? How will the changes affect them?

Here is my attempt at a note about subject_type, tell me what you think about it:

Waivers now have two new attributes, ``subject_type`` and 
``subject_identifier``, to identify the subject of the waiver (that is, the 
particular software artifact that the waiver is about). These new 
attributes replace the ``subject`` attribute which is now deprecated.
The ``subject`` attribute previously accepted any arbitrary key-values, but 
in practice the ``subject`` had to conform to one of several recognised 
structures in order to be usable with Greenwave. This has now been made 
explicit with the ``subject_type`` attribute. See 
:ref:`greenwave:subject_type` in the Greenwave documentation for a list of 
possible subject types and the meaning of their corresponding identifiers.
For backwards compatibility the ``subject`` attribute is still included 
when fetching waivers, and accepted when creating waivers. However if you 
create a new waiver using the deprecated ``subject`` attribute, its 
structure must match one of the recognized subject types, otherwise the 
request will fail with 400 status code. In this release we have implemented 
support for all known subject types in the wild.

Btw this uses an intersphinx reference to Greenwave's docs, we will need to set that up in docs/conf.py for it to work properly.

@dcallagh Oh, nice! It would be better to merge this PR and you create new PR. I feel bit bad implementing changes of other people. Is that OK?

Sure, whatever you prefer.

... so that's :+1: from me to merge this one as is.