generated from sethub/template
131 lines
4.1 KiB
Markdown
131 lines
4.1 KiB
Markdown
# 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
|
|
|