[libxml2]Add libxml2 library

2026-07-26 16:57:28 +08:00
parent 0a44ec8a06
commit e841ac915d
3790 changed files with 668244 additions and 0 deletions
@@ -0,0 +1,130 @@
+# 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
+