msuchane / acorns Goto Github PK

Add a Cizrna subcommand that initializes an empty directory with all the necessary Cizrna configuration files. This would make it more convenient to set up a new release notes project from scratch. The subcommand will probably be called cizrna init.

Display progress bars when downloading tickets from Bugzilla and Jira. With a large number of tickets, the download might even take several minutes, so it would be nice to monitor the progress.

On the implementation side, the only way to do this is probably by splitting the requests into chunks and show progress by chunk.

Some usable libraries that provide progress bar functionality:

• https://crates.io/crates/progressing
• https://crates.io/crates/linya
• https://crates.io/crates/indicatif

Cizrna provides the cizrna ticket subcommand that formats the release note of the single, specified ticket. Currently, the subcommand is broken since the switch to configurable custom fields. Finish the subcommand, which now requires the trackers config file as an argument to recognize custom fields.

Bug status table reports "RN not needed." even for notes that have a valid doc type (like Bug Fix) but previously were marked as No doc update (see BZ#2121709, BZ#2143878).

The top-level chapters that Acorns generates are intended to be included from main.adoc or some other manual content. However, if a chapter captures no release notes, and is empty as a result, Acorns generates nothing in its place. That causes the external include to fail.

Figure out the best solution to empty chapters. Options:

• Generate an empty file that satisfies the external include but doesn't appear in the rendered document. Is non-modular.
• Just fail and let the RN maintainer handle it by commenting out the broken includes. They might forget to re-enable the includes later.
• Fail while generating the file and let the RN maintainer comment out the template. They might forget to re-enable the template later.

Another option:

Acorns can automatically comment out include statements in main.adoc if they target files that this run hasn't generated. The next time the file is generated, Acorns could uncomment the include.

Advantages:

• A clean, modular solution.
• Doesn't risk the breakage caused by manual maintenance.

Disadvantages:

• The RN maintainer might still delete the commented-out include and cause surprises.
• The main.adoc file is technically manual content, so this solution somewhat violates the barrier between generated and manual.

Some RN projects track their RN tickets by attaching them as blockers to a shared, tracker ticket. Enable this as a configuration option for Bugzilla and Jira.

In CoRN 3, the status table shows a combined release version of the whole release notes project. It selects the version that's the most common in all configured tickets.

That leads to situations where the determined version is often behind the actual version of the release notes project, such as when a minor release carries over many of the release notes from the previous, major version, which constitute the majority. For example, the RHEL 9.1 release notes still show the 9.0 version, because the project contains more 9.0 tickets than 9.1.

Use a more accurate and useful version instead. Options that I can think of:

• Provide a manual configuration option to set the version.
• Instead of selecting the most common version, select the "highest" or "most recent" version. This is more complicated because versions are strings with various structures, not just numbers, such as 9.1.0 Beta. Fortunately, the serde library could parse the version strings into rich structures.

If a ticket has several references configured for it, the references change their order every time Cizrna runs. This is probably caused by the changing order in the Bugzilla and Jira responses.

Ways to fix this:

• Sort the references to preserve the order set in the configuration file.
• Sort the references alphabetically. This is much easier to do and might be enough.

Sharing the condition with #22 , if a ticket is private, we should generate a footnote for the ticket ID explaining why there's no link, to prevent recurring bug reports from readers.

In Jira, the Security Level field shall govern if and how private a ticket is.

If a ticket is private, Cizrna never generates a clickable link to it, not even in the internal document version. It would make more sense to distinguish between internal and external here, so that the internal version provides clickable links to all the tickets, regardless of their accessibility.

Consider modifying the template format so that you don't have to repeat the section references several times if the whole list is reusable. This would require an implementation outside of pure YaML as it works now.

I installed the aCoRNs release notes generator on Fedora 39 CSB via official guidance to run as a container.

[astillma@astillma-thinkpadx1nanogen2 ~]$ podman pull quay.io/msuchane/acorns
Trying to pull quay.io/msuchane/acorns:latest...
Getting image source signatures
Copying blob 49ca46f478af skipped: already exists
Copying blob a4641b174d1c skipped: already exists
Copying blob f04c9b876d29 skipped: already exists
Copying blob 7a1369965878 skipped: already exists
Copying config 799213433e done |
Writing manifest to image destination
799213433e04120bc3ca218c7236c194f3c2cffd7832a82c961f42241c908217

[astillma@astillma-thinkpadx1nanogen2 ~]$ podman run -it -e BZ_API_KEY -e JIRA_API_KEY -v .:/mnt/acorns:Z msuchane/acorns acorns
Error: SELinux relabeling of /home/astillma is not allowed

[astillma@astillma-thinkpadx1nanogen2 ~]$ sudo nano /etc/selinux/config
(edited successfully for permissive mode and verified)

[astillma@astillma-thinkpadx1nanogen2 ~]$ sudo setenforce 0

[astillma@astillma-thinkpadx1nanogen2 ~]$ sestatus
SELinux status: enabled
SELinuxfs mount: /sys/fs/selinux
SELinux root directory: /etc/selinux
Loaded policy name: targeted
Current mode: permissive
Mode from config file: permissive
Policy MLS status: enabled
Policy deny_unknown status: allowed
Memory protection checking: actual (secure)
Max kernel policy version: 33

Still encountering the above error, set SELinux mode to permissive in attempt to resolve. Still get "Error: SELinux relabeling of /home/astillma is not allowed". Ideas for next steps?

This is not urgent; I have tabled this effort and successfully installed via copr / dnf.

Thanks,
Andy

Both Bugzilla and Jira require configuration that specifies the names of certain custom fields, such as doc text or target release. However, the two services don't have the same requirements.

Bugzilla requires:

• doc_type
• doc_text
• doc_text_status
• subsystems
• target_release

Jira requires:

• doc_type
• doc_text
• doc_text_status
• subsystems
• docs_contact

Adjust the required fields in tracker configuration to only require the necessary fields for each service.

Cizrna gave the following warning in the pipeline log:

13:43:22 [WARN] Fields are empty in ticket RHELPLAN-80695: ["customfield_12317322", "customfield_12310211"]

However, the ticket is only included in tickets.yaml for reference, and therefore does not have to be set up in the same way other Release Note tickets do.

Marek, could you please look into a way these referential ticket could bypass the standard RN validation to avoid triggerring needless warnings?

Thank you so much :)

Gabi

Check every release note with the Vale linter.

The results of the Vale checks could be available in the status table. Given how long the listing can be, hide the full report in a tooltip or something like that.

We could either check the raw doc text, or preferably the final release note, because Cizrna might edit the doc text with an auto-generated title, for example.

Vale can run in the RN repo CI, but the complete document report is too long and it's difficult to trace errors back to their original tickets.

Vale is available from the following repositories:

• Copr: https://copr.fedorainfracloud.org/coprs/mczernek/vale/
• Docker Hub: https://hub.docker.com/r/jdkato/vale

Provide an option that Cizrna auto-generates a title for each release note. The title lists the ticket ID, and perhaps the ticket summary or other metadata. It replaces the label that writers otherwise specify at the top of the doc text.

The RHEL 9.2 bug status table sometimes doesn't count correctly.

For example, if I filter for my user name, the table lists 15 tickets in overall status OK and 2 in "RN not approved". However, in the counter table below, it shows "complete: 15" and "incomplete: 1"

Also, if I filter for another user, the table lists 8 tickets in overall status OK and 5 in "RN not approved". The counter table below shows "complete: 7" and "incomplete: 5"

As an option, save the generated files to a different, separate directory on the system, or to a different Git repository, perhaps even a remote one.

This would allow uses to keep the RN configuration in one repository and the generated AsciiDoc files in another, which is what RHEL RNs do in a post-processing step after CoRN runs.

A typo in an override syntax (e.g. subsystem: instead of subsystems:) doesn't warn there is a problem and just doesn't work. In case there are multiple SSTs, the build fails with a duplicate ID error despite the attempt for an SST override. In other cases, it just silently does nothing, and notes are sorted into an incorrect chapter.

Please add a warning that an override is malformed to prevent these cases - or even better, make the pipeline fail in such a case.

Several people want to use Cizrna on macOS. Building from source is possible, but it's not as convenient as it could be, especially because the user can easily forget to update the package.

In addition to building from source, provide Cizrna as a tap (package) using the Homebrew package manager. Cizrna likely wouldn't get accepted into the main Homebrew repository, but we can maintain a custom add-on repository on Github. See https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap for instructions.

With Homebrew as a central package manager, users are more likely to update.

See my own Homebrew repository: https://github.com/msuchane/homebrew-repo.

Currently, if the docs contact custom field is missing in a ticket, the CIzrna build fails. RHEL release notes maintainers would prefer if instead Cizrna printed out a warning and used a docs contact placeholder: Missing Docs Contact.

Highlight the “unknown” RN type and exclude the former “RN only” impact value.

See https://issues.redhat.com/browse/RIJ-929 (RH ticket).

It's convenient when every release note has a HTML anchor attached to its heading. That way, you can link a specific release note in the document.

Add IDs to release note labels. Make sure that the IDs are unique, for cases where a release note is reused several times in the document.

Lenka:

Would it be difficult to make List of tickets... use xref to the individual notes instead?

It seems more user-friendly - find the component of interest and quickly get to all related notes.
And only below the actual note, there would be a link to public BZ or just a plain-text tracker with a tooltip or something.

This depends on issue #10.

Module IDs aren't very robust. Because modules in release notes tend to have many of the same names, such as Desktop repeated for each doc type, the IDs require a slightly different structure than in a regular FCC repository.

Also see how {context} could fit into this.

Most tickets on our Jira instance are private, but some are already public and their number will increase. Cizrna considers all Jira tickets as private because I don't know which field marks that the ticket is either private or public.

Find out which field is responsible for this property, and implement a similar behavior to that with Bugzilla.

As a result, links to public tickets will be clickable in the release notes.

If the release notes project pulls in tickets from several different namespaces in the ticket tracker, such as both RHELPLAN and RHEL, the tickets might need different custom field codes. For these cases, it would be nice if the custom field settings weren't individual strings, but rather lists of strings, so that Cizrna can try out several fields in a row for each ticket and see which works.

Detect if the tickets configuration file contains any duplicate entries.

Two entries are duplicates if their tracker and key or search are identical. Ignore overrides and references for this purpose.

Currently, duplicates result in a build error that's hard to understand.