Sentry Maven Skin

The Sentry Maven Skin is an Apache Maven site skin to be used to generate Sentry's technical user documentation, using modern-era development tools (git, maven, markdown), and producing modern-era Web-based documentation (HTML5, Bootstrap, etc.)

To use the Sentry Maven Skin, read the full documentation.

Maven Site Plugin 3.21.0 or newer (including 4.x) is required. Versions up to 3.12.1 use Velocity 1.7, which conflicts with the Velocity 2.x tools supplied by maven-skin-tools. Use the site.xml 2.0 schema for both supported plugin families.

Structure and technologies

Beware that this project is a baroc mix of languages, frameworks and libraries:

• Java for some backend HTML processing
• Javascript-in-Java with GraalVM for building the index
• Velocity for templating
• AngularJS for front-end logic
• Various HTML, CSS and JS frameworks and libraries (Bootstrap, etc.)
• npm and Gulp.js to build the front-end
• Groovy for validating the integration tests

The Sentry Maven Skin project is made of several main components:

• ./src/main/webapp/**: the front-end web app, including CSS, JS, HTML templates, etc.
• ./src/main/webapp/css/scss/**: modular SCSS sources compiled into sentry.css, prism-theme.css, copy-to-clipboard.css, and print.css during Gulp build
• ./src/main/webapp/site.vm: the main Velocity template entry point
• ./src/main/webapp/*.vm: modular Velocity templates (head, banner, menu, content, footer, etc.)
• ./package.json: for NPM
• ./gulpfile.js: to build and minify the web app
• ./src/it/studio-km: integration test for the minimum supported Maven Site Plugin 3.21.0
• ./src/it/site4: integration test for Maven Site Plugin 4.x

Build

The build is done with Maven with the below command:

mvn verify

Build steps:

• NodeJS is installed in ./node (and is ignored by Git)
• npm install is run to get all dependencies listed in package.json, which are installed in the ./node_modules (also ignored by Git)
• gulp is run with ./gulpfile.js to build the front-end web app (lint, template embedding, SCSS compilation to temp CSS before useref concatenation/minification, etc.), and the result is stored in ./target/dist
• i18n bundles (resources*.properties) are authored in UTF-8 under src/main/webapp and converted by Gulp to Java 8-safe \uXXXX escaped bundles in target/dist/META-INF/maven
• The Maven skin JAR is assembled in ./target
• A temporary local Maven repository is set up with both JAR artifacts (the skin and the Velocity tools)
• A test project is set up in ./target/it and mvn site is run on this test project
• The result validated with a Groovy script

Release automation

The GitHub release workflow uses version 6 of the shared Maven Central workflow. Its release and GitHub Pages jobs use Ubuntu 24.04 and Node.js 24 actions. The nodeVersion input separately selects Node.js 20 for building the frontend.

Test

While modifying the Sentry Maven Skin, you will want to see how your changes are reflected in a test documentation project.

Conveniently, the project comes with integration tests, i.e. a documentation project that is automatically built with the skin as it is in the workspace. The integration test is run with the below command:

mvn verify

Building This Project's Own Documentation

This project uses itself as its own Maven skin (dogfooding). Because of this, you must run mvn install before mvn site to ensure the skin JAR is available in your local Maven repository:

mvn install site

Running mvn site alone will fail because the skin artifact won't be found.

This command builds the skin and run it against a documentation project. The result can be seen in ./sentry-maven-skin/target/it/studio-km/site/*.html.

We recommend running http-server to browse the result. Install with:

npm install --global http-server

Launch a Web server with the generated test documentation with:

http-server sentry-maven-skin/target/it/studio-km/target/site

Integration test build logs are stored in target/it/*/build.log. Failed test logs are also printed in the Maven console, including GitHub Actions output.

UI Baseline Regression Suite

The repository includes a Playwright-based UI suite (Chromium) with visual snapshots, computed-style dumps, and AngularJS protection checks. Build both integration sites and the project documentation before running it:

mvn clean install site
npm run ui:baseline:install
npm run ui:baseline:capture
npm run ui:baseline:verify

• Baselines are stored under tests/baseline/
• Comparison reports are generated under tests/results/diff-report.*

Formatting and EOL Policy

• Text files are expected to be UTF-8 (no BOM) with CRLF line endings.
• .editorconfig and .gitattributes enforce the policy in editors and Git checkouts.
• Prettier is configured with endOfLine: "crlf" and can be run with:

npm run format
npm run format:check