1# Maintainer's Guide 2 3## Working with the test suite 4 5Most of the tests are contained in the `runtest` executable which 6generally reads test cases from the `test` directory and compares output 7to files in the `result` directory. 8 9You can simply add new test cases and run `runtest -u` to update the 10results. If you debug test failures, it's also useful to execute 11`runtest -u` and then `git diff result` to get a diff between actual and 12expected results. You can restore the original results by running 13`git restore result` and `git clean -xd result`. 14 15## Generated files 16 17The documentation and other generated files can be rebuilt by running 18 19 make -C doc rebuild 20 21This requires `xsltproc`, the DocBook stylesheets in your XML Catalog 22and the libxml2 Python bindings to be installed, so it's best done on a 23Linux system. On Debian/Ubuntu, try 24 25 apt install xsltproc python3-libxml2 docbook-xsl docbook-xml 26 27doc/apibuild.py generates doc/libxml2-api.xml which is used to generate 28 29- API documentation with XSLT stylesheets 30- testapi.c with gentest.py 31- Python bindings with python/generator.py 32 33Man pages and HTML documentation for xmllint and xmlcatalog are 34generated with xsltproc and DocBook stylesheets. 35 36## Making a release 37 38### Rebuild generated files and documentation 39 40See above for details and run `make -C doc rebuild`. 41 42Look for new warning messages and inspect changes for correctness 43before committing. 44 45### Update the NEWS file 46 47You can get started by running 48 49 git log --format='- %s (%an)' [previous-release-tag].. 50 51### Bump the version number 52 53Update the version number in `VERSION` if you haven't done so already. 54 55### Build the tarball 56 57I'd recommend to build the tarball by running 58 59 make distcheck 60 61which performs some useful checks as well. 62 63### Upload the tarball 64 65Follow the instructions at 66<https://wiki.gnome.org/MaintainersCorner/Releasing>: 67 68 scp libxml2-[version].tar.xz master.gnome.org: 69 ssh master.gnome.org ftpadmin install libxml2-[version].tar.xz 70 71### Tag the release 72 73Create an annotated tag and push it: 74 75 git tag -a [version] -m 'Release [version]' 76 git push origin [version] 77 78### Create a GitLab release 79 80Create a new GitLab release on 81<https://gitlab.gnome.org/GNOME/libxml2/-/releases>. 82 83### Announce the release 84 85Announce the release on https://discourse.gnome.org under topics 'libxml2' 86and 'announcements'. 87 88## Breaking the ABI 89 90Unfortunately, libxml2 exposes many internal structs which makes some 91beneficial changes impossible without breaking the ABI. 92 93The following changes are allowed (after careful consideration): 94 95- Appending members to structs which client code should never allocate 96 directly. A notable example is xmlParserCtxt. Other structs like 97 xmlError are allocated directly by client code and must not be changed. 98 99- Making a void function return a value. 100 101- Making functions accept const pointers unless it's a typedef for a 102 callback. 103 104- Changing signedness of struct members or function arguments. 105 106## Updating the CI Docker image 107 108Note that the CI image is used for libxslt as well. First create a 109GitLab access token with maintainer role and `read_registry` and 110`write_registry` permissions. Then run the following commands with the 111Dockerfile in the .gitlab-ci directory: 112 113 docker login -u <username> -p <access_token> \ 114 registry.gitlab.gnome.org 115 docker build -t registry.gitlab.gnome.org/gnome/libxml2 - \ 116 < .gitlab-ci/Dockerfile 117 docker push registry.gitlab.gnome.org/gnome/libxml2 118 119