# 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

Update the version number in `VERSION` 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 on https://discourse.gnome.org under topics 'libxml2'
and 'announcements'.

## 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