Add "How to make a libxkbcommon release"

[bluetech]

I hope I didn't forget anything. We can certainly automate some of this, but this is documenting what I am currently doing.

Note that I explicitly decided to remove publishing a tarball. Given what happened with xz backdoor, I think we are better off without them. I'm pretty sure most distros build directly from git these days. We should make a prominent note of this change in the announcement email. Old tarballs will not be removed.

Let me know if you have any comments.

[wismill]

I'm pretty sure most distros build directly from git these days.

It seems openSUSE does not. I do not know for others.

[bluetech]

It seems openSUSE does not. I do not know for others.

Good to know. I am sure they have support for git, but let's let them know.

---

@DimStar77 If I understand correctly, you are the maintainer of the libxkbcommon package in openSUSE (apologies if not). In the next release, we are planning to drop publishing a tarball, instead instructing distros to build directly from git. The openSUSE package does use the tarball, if you'd have trouble switching, let us know.

[wismill]

@bluetech could you transform the items into checklists? So that we can copy them as a template when creating a release issue/MR.

[bluetech]

Good idea, done.

[bluetech]

Hmm I figure since we're removing the tarballs & sha-256, and git tags are not immutable, we should add the commit hash to the announcement mail. I'll add it to the template.

[wismill]

We should define a range of versions for Doxygen. It is not that reliable, things (e.g. links) got broken/repaired multiple times.

IIRC our runners use a version that is bit old and there are some issues in the display.

[bluetech]

Perhaps the best way is to download the docs from CI? E.g. in the latest pages workflow run, there is a "Artifact download URL" https://github.com/xkbcommon/libxkbcommon/actions/runs/12350295345/job/34462865916.

[wismill]

That would be the best way indeed. But the issue is that Doxygen breaks things regularly (they do not have much regression test suite), so we need some manual control.

E.g. currently I have the latest version (1.12.0) and I get these warnings:

...
home/user/Repositories/libxkbcommon/include/xkbcommon/xkbcommon.h:1775: warning: unable to resolve reference to 'virtual-modifier-def' for \ref command
/home/user/Repositories/libxkbcommon/include/xkbcommon/xkbcommon.h:1797: warning: unable to resolve reference to 'virtual-modifier-def' for \ref command
...

This is fixed in current master, which we could use if generating the doc manually.

All in all I would like to drop Doxygen, but it seems there is no replacement that’s as complete, easy to install and free.

[bluetech]

E.g. currently I have the latest version (1.12.0) and I get these warnings:

Indeed I have seen those.

All in all I would like to drop Doxygen, but it seems there is no replacement that’s as complete, easy to install and free.

In the mean time, let's try to publish the docs with a good build and hope they release a new version soon...

[whot]

I'm pretty sure most distros build directly from git these days.

ftr, fedora doesn't either. we have copied-everywhere shell scripts to be able to build from git but right now we're using the tarballs.

I suspect the vast majority of distros will simply switch to the github auto-generated tarballs that are created when you create a release here on the repo, e.g. https://github.com/xkbcommon/libxkbcommon/releases/tag/xkbcommon-1.7.0 :)

[wismill]

I suspect the vast majority of distros will simply switch to the github auto-generated tarballs that are created when you create a release

@whot Is it secure though? Can someone mess with these files or does Github ensure their integrity?

[whot]

@whot Is it secure though? Can someone mess with these files or does Github ensure their integrity?

I think you can delete a release and make a new one in which case a new zip file would be generated. The best workaround for this would be to push out the release, generate the sha and then publish that somewhere independently.

I don't think there's an easy-to-exploit way of changing those generated files and we're probably not in the line of projects worth that much effort to take over a tarball :)

[wismill]

Suggested change

	- [ ] Add the doc for the release: `cp -r <xkbommon>/build/html doc/<MAJOR.MINOR.PATCH>`.
	- [ ] Add the doc for the release: `cp -r <xkbommon>/build/html doc/<MAJOR.MINOR.PATCH>`. Check carefully that there is no warning during generation with Doxygen. It may be necessary to use another version of Doxygen to get a clean build. Building from source using the main branch is also a good option.

From our discussion above. The main point it to warn to check the Doxygen generation, feel free to remove the rest.