libxml2/MAINTAINERS.md

Maintainer's Guide

Working with the test suite

Most of the tests are contained in the runtest executable which generally reads test cases from the test directory and compares output to files in the result directory.

You can simply add new test cases and run runtest -u to update the results. If you debug test failures, it's also useful to execute runtest -u and then git diff result to get a diff between actual and expected results. You can restore the original results by running git restore result and git clean -xd result.

Generated files

The documentation and other generated files can be rebuilt by running

make -C doc rebuild

This requires xsltproc, the DocBook stylesheets in your XML Catalog and the libxml2 Python bindings to be installed, so it's best done on a Linux system. On Debian/Ubuntu, try

apt install xsltproc python3-libxml2 docbook-xsl docbook-xml

doc/apibuild.py generates doc/libxml2-api.xml which is used to generate

• API documentation with XSLT stylesheets
• testapi.c with gentest.py
• Python bindings with python/generator.py

Man pages and HTML documentation for xmllint and xmlcatalog are generated with xsltproc and DocBook stylesheets.

Making a release

Rebuild generated files and documentation

See above for details and run make -C doc rebuild.

Look for new warning messages and inspect changes for correctness before committing.

Update the NEWS file

You can get started by running

git log --format='- %s (%an)' [previous-release-tag]..

Bump the version number

Edit the version number in configure.ac if you haven't done so already.

Build the tarball

I'd recommend to build the tarball by running

make distcheck

which performs some useful checks as well.

Upload the tarball

Follow the instructions at https://wiki.gnome.org/MaintainersCorner/Releasing:

scp libxml2-[version].tar.xz master.gnome.org:
ssh master.gnome.org ftpadmin install libxml2-[version].tar.xz

Tag the release

Create an annotated tag and push it:

git tag -a [version] -m 'Release [version]'
git push origin [version]

Create a GitLab release

Create a new GitLab release on https://gitlab.gnome.org/GNOME/libxml2/-/releases.

Announce the release

Announce the release by sending an email to the mailing list at xml@gnome.org.

Breaking the ABI

Unfortunately, libxml2 exposes many internal structs which makes some beneficial changes impossible without breaking the ABI.

The following changes are allowed (after careful consideration):

• Appending members to structs which client code should never allocate directly. A notable example is xmlParserCtxt. Other structs like xmlError are allocated directly by client code and must not be changed.

• Making a void function return a value.

• Making functions accept const pointers unless it's a typedef for a callback.

• Changing signedness of struct members or function arguments.

Updating the CI Docker image

Note that the CI image is used for libxslt as well. First create a GitLab access token with read_registry and write_registry permissions. Then run the following commands with the Dockerfile in the .gitlab-ci directory:

docker login -u <username> -p <access_token> \
    registry.gitlab.gnome.org
docker build -t registry.gitlab.gnome.org/gnome/libxml2 - \
    < .gitlab-ci/Dockerfile
docker push registry.gitlab.gnome.org/gnome/libxml2