onboard-contributor

name	onboard-contributor
description	Guide a new contributor through the rundeck OSS repo. Use when someone is getting started with the project, asking how to build/test/contribute, or setting up their development environment.

Onboard Contributor

Guides new contributors (external or internal) through the rundeck OSS development environment.

When to Use

• New contributor asking how to get started
• Questions about building or running the project
• Questions about how to contribute a plugin, bug fix, or feature
• Setting up a development environment

Process

Phase 1: Environment Check

Check the contributor's environment:

java -version   # Must be Java 17
node -v         # Check .nvmrc for required version
./gradlew --version

If Java is wrong: suggest jenv, sdkman, or asdf. If Node is wrong: suggest nvm use (after checking .nvmrc).

Phase 2: Project Overview

Explain the structure:

rundeck/
├── rundeckapp/       Main Grails application (controllers, services, Vue frontend)
├── core/             Core Java library (plugin interfaces, shared utilities)
├── functional-test/  Selenium and API functional tests
├── grails-webhooks/  Webhooks plugin
└── gradle.properties All dependency versions defined here

Key points:

• Backend: Grails 7 / Spring Boot 3 / Groovy 4 — use @CompileStatic on all classes
• Frontend: Vue 3 + TypeScript in rundeckapp/grails-spa/packages/ui-trellis/
• Tests: Spock for backend, Jest for frontend, Selenium for E2E
• Migrations: Liquibase in rundeckapp/grails-app/migrations/ — never modify existing ones

Phase 3: First Build

# Full build, skip tests for speed (~4-8 min)
./gradlew build -x check

# If it fails, try cleaning first
./gradlew clean && ./gradlew build -x check

Phase 4: Running Tests

# Backend unit tests
./gradlew test

# Frontend unit tests
UI=rundeckapp/grails-spa/packages/ui-trellis
npm run --prefix "$UI" ci:test:unit

# Specific test class
./gradlew test --tests "com.example.MySpec"

Phase 5: Making a Contribution

For a bug fix:

1. Write a failing test that reproduces the bug (Spock for backend, Jest for frontend)
2. Fix the bug
3. Verify the test now passes
4. Run ./gradlew build -x check to verify compilation

For a new plugin:

• Use the create-plugin skill

For a new API endpoint:

• Use the create-api-endpoint skill

PR conventions:

• Include tests for all new behavior
• All PRs must pass CI before merge
• See CONTRIBUTING.md in the repo root for the full contribution guide

Phase 6: Code Standards Summary

Standard	Rule
Groovy classes	@CompileStatic required (or @GrailsCompileStatic for Grails artifacts)
Tests	Spock only — no new JUnit
Vue components	Options API default, scoped styles, data-testid in tests
DB migrations	Never modify existing — create new ones
Strings in Vue	Always use $t() — no hardcoded English
OkHttp responses	Must be closed or body consumed

Checklist

• Java 17 confirmed
• Node.js version matches .nvmrc
• ./gradlew build -x check passes
• Contributor knows where controllers, services, Vue components live
• Contributor understands test requirements (Spock, Jest, Selenium)
• Contributor knows the plugin development path (if applicable)