Skip to content

Latest commit

 

History

History
239 lines (183 loc) · 11.2 KB

AGENTS.md

File metadata and controls

239 lines (183 loc) · 11.2 KB

AGENTS.md - AI Coding Agent Instructions

This file provides instructions for AI coding agents (GitHub Copilot, Cursor, Cline, etc.) to effectively work with the Sentry Maven Skin project.

Important Reminders

Caution

Keep documentation in sync with code changes!

  • When behavior of the skin changes, review and update the documentation site (src/site/markdown/*.md)
  • When project structure or build process changes, update AGENTS.md and README.md
  • Always verify documentation renders correctly after skin changes: mvn clean install site

Project Overview

The Sentry Maven Skin is an Apache Maven site skin that transforms Markdown files into a modern HTML5/Bootstrap documentation website with search, syntax highlighting, and responsive design.

Key Technologies

Technology Purpose Location
Velocity HTML templating src/main/webapp/*.vm
JavaScript Frontend logic (AngularJS) src/main/webapp/js/*.js
CSS/SCSS Styling src/main/webapp/css/
HTML Angular templates src/main/webapp/*.html
Gulp.js Build system for frontend gulpfile.js
Maven Build orchestration pom.xml
Groovy Integration test verification src/it/*/verify.groovy

Required Dependency: Maven Skin Tools

The skin requires maven-skin-tools (org.sentrysoftware.maven:maven-skin-tools) which provides custom Velocity tools for HTML processing, search indexing, image optimization, and more. Refer to the maven-skin-tools documentation when working on Velocity templates.

Project Structure

sentry-maven-skin/
├── src/
│   ├── main/webapp/          # Frontend source code
│   │   ├── site.vm           # Main Velocity template entry point
│   │   ├── init.vm           # Initialization and variable setup
│   │   ├── macros.vm         # Reusable Velocity macros
│   │   ├── head.vm           # HTML <head> section
│   │   ├── metadata.vm       # Meta tags and JSON-LD
│   │   ├── banner.vm         # Header banner and navigation
│   │   ├── left-menu.vm      # Left sidebar menu
│   │   ├── main.vm           # Main content area
│   │   ├── content.vm        # Body content processing
│   │   ├── blockquotes.vm    # UI components (tabs, accordions, etc.)
│   │   ├── footer.vm         # Page footer
│   │   ├── js.vm             # JavaScript includes
│   │   ├── css/              # Compiled stylesheet outputs (sentry.css, prism-theme.css, copy-to-clipboard.css, print.css)
│   │   ├── js/               # JavaScript files (site.js, site-index.js)
│   │   └── fonts/            # Custom fonts
│   ├── it/                   # Integration tests
│   │   ├── settings.xml      # Maven settings for IT
│   │   ├── studio-km/        # Main test project (Maven Site Plugin 3.x)
│   │   └── site4/            # Test project for Maven Site Plugin 4.x
│   └── site/                 # Project's own documentation (dogfooding)
├── gulpfile.js               # Gulp build tasks for frontend
├── package.json              # Node.js dependencies
├── pom.xml                   # Maven build configuration
└── target/                   # Build output (gitignored)

Note

src/main/webapp/css/scss/ contains the modular SCSS sources. Gulp compiles scss/sentry.scss, scss/prism-theme.scss, scss/copy-to-clipboard.scss, and scss/print.scss into target/tmp/webapp/css/ before useref.

Building the Project

Standard Build Command

mvn clean install site

This command:

  1. Cleans previous build artifacts
  2. Installs Node.js locally and runs npm ci
  3. Runs Gulp to build, lint, and minify frontend assets (including SCSS compilation of css/scss/*.scss entrypoints into temp CSS before useref, and conversion of UTF-8 resources*.properties files into Java 8-safe \uXXXX escaped bundles in META-INF/maven)
  4. Packages the Maven skin JAR
  5. Runs integration tests (studio-km and site4)
  6. Generates this project's own documentation site

Important

Always use mvn clean install site for a full rebuild. The clean phase is needed because Maven's incremental build doesn't always detect changes in Velocity templates or frontend assets. The install phase must run before site because this project uses itself as its own skin (dogfooding).

Build Output

Output Description
target/sentry-maven-skin-*.jar The skin artifact
target/it/studio-km/target/site/ Integration test output (3.x)
target/it/site4/target/site/ Integration test output (4.x)
target/site/ This project's documentation
target/it/*/build.log Build logs (check on failure)

Previewing Generated Sites

# Install http-server globally (once)
npm install --global http-server

# Serve any generated site
http-server target/it/studio-km/target/site   # Integration test (3.x)
http-server target/it/site4/target/site       # Integration test (4.x)
http-server target/site                        # Project documentation

Making Changes

  1. Edit files in src/main/webapp/ (frontend) or src/site/ (documentation)
  2. Run mvn clean install site
  3. Preview results in target/it/studio-km/target/site/ or target/site/

Tip

When changing skin behavior, always run mvn clean install site and check both integration tests (studio-km for Maven Site Plugin 3.x, site4 for 4.x) and the project's own documentation site.

When the behavior of the skin is not changed (for example when you're updating the documentation or the integration tests), you must not run a full build cycle:

  • For documentation only changes, simply run mvn site.
  • For tests changes, run mvn verify.

Quick Iteration for Integration Tests

When debugging integration tests, you can iterate faster:

  1. Edit files in src/it/studio-km/ or src/it/site4/
  2. Run mvn verify (faster than full install site)
  3. Check target/it/*/build.log for output

Debugging Velocity templates: Use $log.debug(...) in .vm files to output debug information to build.log:

#call($log.debug("Variable value: $myVariable"))
#call($log.debug($bodyContent))

Code Formatting

JavaScript, CSS, HTML

npm run format        # Auto-fix formatting (Prettier)
npm run format:check  # Check only (CI mode)
npm run lint          # Check for linting issues (ESLint)
npm run lint:fix      # Auto-fix linting issues

Formatting policy:

  • Text files must be UTF-8 without BOM and use CRLF line endings.
  • .editorconfig, .gitattributes, and Prettier (endOfLine: "crlf") are the primary enforcement mechanisms.

Velocity Templates

No automated formatting. Follow these conventions:

  • Indentation: Use tabs
  • Comments: #* ... *# for multi-line, ## ... for single-line
  • Whitespace control: Use #*...*# to suppress unwanted EOLs
#**
 * Macro documentation
 **
*##macro(myMacro $param)#*
    *##if ($param)#*
        *#<div>$param</div>#*
    *##end#*
*##end

Testing

Integration tests run automatically during mvn install. Each test:

  1. Builds a documentation site using the skin
  2. Verifies output with verify.groovy using JSoup for HTML parsing

The tests use JSoup CSS selectors to verify HTML structure, making assertions more readable and robust:

// Example: Check meta tag content
assert doc.select('meta[name=description]').attr('content').startsWith('Expected...') : "Description must be set"

// Example: Verify element structure
assert doc.select('main.main-content .search-results').size() > 0 : "Search results must be inside main"
Test Project Maven Site Plugin Source Location
studio-km 3.x src/it/studio-km/
site4 4.x src/it/site4/

Common Issues

Problem Solution
Changes not reflected Run mvn clean install site (not just mvn site)
NoSuchFileException: target/classes Run install before site (dogfooding requirement)
NPM errors Delete node/, node_modules/, package-lock.json, rebuild
Velocity syntax errors Check target/it/*/build.log for details

Code Style Guidelines

  • JavaScript: Double quotes, AngularJS 1.x patterns
  • CSS: Bootstrap conventions, CSS variables for theming
  • Velocity: Use $!variable for potentially null values, #call() to ignore return values

Key Files

File Purpose
src/main/webapp/site.vm Main template entry point
src/main/webapp/init.vm Variable initialization and setup
src/main/webapp/macros.vm Reusable Velocity macros
src/main/webapp/head.vm HTML head section (CSS, meta tags)
src/main/webapp/metadata.vm Meta tags and schema.org JSON-LD
src/main/webapp/banner.vm Header banner and top navigation
src/main/webapp/left-menu.vm Left sidebar navigation menu
src/main/webapp/main.vm Main content wrapper and search results
src/main/webapp/content.vm Body content processing (TOC, images, etc.)
src/main/webapp/blockquotes.vm UI components (tabs, accordions, collapsibles)
src/main/webapp/footer.vm Page footer with copyright and links
src/main/webapp/js.vm JavaScript includes
src/main/webapp/js/site.js Main AngularJS application
src/main/webapp/css/scss/sentry.scss Main SCSS entrypoint
src/main/webapp/css/scss/prism-theme.scss Prism theme SCSS source
src/main/webapp/css/scss/copy-to-clipboard.scss Copy-to-clipboard SCSS source
src/main/webapp/css/scss/print.scss Print stylesheet SCSS source
src/site/markdown/*.md Project documentation (dogfooding)

Getting Help