validator/visualization/doc/development.md

Development of XRechnung Visualization

Project Structure

• src contains the source files.
• src/test contains example instances of invoice files.
• src/xsd contains the schema of the intermediate xml.
• src/xsl contains the transformation files.

Dependencies Overview

Compile Time

That is for creating visualizations.

• Apache FOP
• Saxon HE
• XRechnung-Testsuite

Testing

• validator-configuration-xrechnung
• VNU HTML Validator

The build environment

This repository contains an ANT build.xml for development and test.

We recommend Apache Ant version 1.10.x or newer (but should work with > 1.8.x).

The main ant targets for development are:

• clean deletes all generated folders i.e. foremost the build directory.
• transform-to-visualization generates all visualizations from xrechnung-testsuite and test instances in src/test
• test validates source UBL or CII XML against XRechnung, transforms to XR Sem Model and schema validates results and transforms and test HTML and PDF visualization
• and dist (creating the distribution artefact)

However, because of the complex dependencies, you may only expect transform-to-visualization target to work without any customizations.

Test dependencies on the fly

If you build own local custom versions of dependencies such as XRechnung Testsuite or Validator Configuration XRechnung, you can customize the ant build at runtime.

Test with local Validator Configuration XRechnung

If you want to test with a local validator configuration xrechnung installation set the ant property validator.repository.dir to the directory (full path) like e.g. validator.repository.dir=/mnt/c/data/git-repos/validator-configuration-xrechnung/build (Linux). To execute the test target, for example, call

ant -Dvalidator.repository.dir=/home/renzo/projects/validator-configuration-xrechnung/build test

For Windows users:

ant "-Dvalidator.repository.dir=/c:/dev/git/validator-configuration-xrechnung/build" test

Development properties file

In order to configure more complex adoption to the local development needs, you have to load a set of different properties from a file.

We provide the development.build.properties.example file for the most common properties to be set different than default. It contains some documentation.

You have to copy the file to e.g. development.build.properties and you have to explicitly provide the property file location at CLI for your development (otherwise tests will always fail or not be executed at all).

Distribution

The ant target dist creates the distribution zip Archive for releases.

Release

Checklist

• Are all issues scheduled for the release solved?
• Is everything merged to master branch?
• Make sure that CHANGELOG.md is up to date
• Make sure all external contributors are mentioned

Prepare

• Make sure you committed and pushed everything

• Create the distribution

  • Use the clean target to build and test all from scratch

ant clean dist

• Tag the last commit according to the following naming rule: v${xr-visu.version.full} e.g. git tag v2024-06-20 && git push origin v2024-06-20

Publish

• Draft a new release at https://github.com/itplr-kosit/xrechnung-visualization/releases/new
  • Choose the git tag you just created
• Add release title of the following scheme: XRechnung Visualization ${xr-visu.version.full} compatible with XRechnung ${xrechnung.version}
• Copy & paste the high quality changelog entries for this release from CHANGELOG.md.
• Upload distribution zip and tick mark this release as a pre-release.
• If all released components are checked to be okay, then uncheck pre-release.

Post-Release

• Change the version of this component in build.xml to the next release and commit
• bump version
• update CHANGELOG.md

You are done 😄