transformed

visualization/doc/development.md

@@ -0,0 +1,112 @@
+# 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
+
+```shell
+ant -Dvalidator.repository.dir=/home/renzo/projects/validator-configuration-xrechnung/build test
+```
+
+For Windows users:
+
+```shell
+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 :smile: