| # 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 | |
| Some source code is generated with Python scripts in the `tools` | |
| directory. | |
| - `tools/genChRanges.py` generates code to handle character ranges | |
| from chvalid.def: | |
| - `chvalid.c` | |
| - `include/libxml/chvalid.h` | |
| - `tools/genEscape prints lookup tables for serialization. | |
| - `tools/genHtml5LibTests.py` creates test cases and expected results | |
| from the html5lib test suite: | |
| - `test/html-tokenizer` | |
| - `result/html-tokenizer` | |
| - `tools/genHtmlEnt.py` prints lookup tables for HTML5 named character | |
| references (predefined entities): | |
| - `html5ent.inc` | |
| - `tools/gentest.py` generates test code using the Doxygen XML output: | |
| - `testapi.c` | |
| - `tools/genUnicode.py` generates code to handle Unicode ranges | |
| from Unicode data files: | |
| - `xmlunicode.c` | |
| ## Making a release | |
| ### 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. | |
| ### Commit and verify tarball | |
| Release tarballs are generated with a CI job and the `.gitlab-ci/dist.sh` | |
| script. Push the release commit and inspect the tarball artifact generated | |
| by Gitlab CI. | |
| ### Tag the release | |
| Create an annotated tag and push it: | |
| git tag -a [version] -m 'Release [version]' | |
| git push origin [version] | |
| This will upload the release to the downloads server using the GNOME | |
| Release Service. For more details, see | |
| <https://handbook.gnome.org/maintainers/release-pipeline.html> | |
| ### Create a GitLab release | |
| Create or update a 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'. | |
| ## Removing public API functions | |
| General process to remove public API functions (or variables): | |
| - Make sure that there's a reasonable alternative. | |
| - Mark the function as deprecated in the documentation and mention | |
| alternatives. | |
| - Mark the function as XML_DEPRECATED in the header files. | |
| - For whole modules: disable the module by default and only enable | |
| it in "legacy mode". | |
| - Remove the function body and make the function return an error code | |
| or a no-op. Make sure that the symbol is kept and exported. This | |
| should only be done after allowing users enough time to adjust. | |
| - At the next ABI bump, remove the symbol completely. | |
| You can wait for the next feature release between some of the steps to | |
| make the process more gradual. | |
| ## 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 maintainer role and `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 | |