Repository navigation
Development
Building JobWarden from its sources, testing it, translating it and releasing it. How the code is organized, and the conventions the build checks, are on What's what. CONTRIBUTING.md says how to propose a change.
Requires JDK 25 or later and Docker. The app starts its own PostgreSQL container from app/compose.yaml:
./mvnw -pl app -am spring-boot:runBuild and run every test (the database tests use Testcontainers, so Docker must be running), with NullAway's checks as CI runs them:
./mvnw verify -PnullawayPages are server-rendered with Thymeleaf; HTMX handles partial updates without a page reload. The menu lists the Search Builder, Who's hiring, AI Assistant, Auto-apply, Jobs, Pipeline, Calendar, Salaries and CV; Settings are in the profile menu at its foot. From 1024 pixels wide every page fills the window (page-full in app.css), and its lists and panels scroll on their own: the jobs under their header row, each pipeline column, the calendar. Pages of two panels side by side (the AI Assistant, the CV, the salaries, a job's page) do so from 1280 pixels (page-split, with scroll-panel for each panel); narrower, their panels stack and the page scrolls. Tailwind CSS is compiled during the Maven build, which downloads its own Node into web/target/, so nothing extra needs installing. While editing templates, keep the CSS up to date with:
./mvnw -pl web frontend:npm@tailwind-watchThe pages' JavaScript is plain ES modules, with no bundler: static/js/app.js imports one module per feature from static/js/app/ (dialogs, forms, the list's selection, fields of chips, the calendar, reminders, the pipeline...). A module listens for the events only it handles; a click, change or input that several features might claim goes through one ordered chain in app.js, where the first handler that says it was its own ends it. ESLint checks it on ./mvnw verify (web/eslint.config.mjs); in web/, npm run lint runs it alone.
The pages are in English, Romanian, French, German, Polish, Spanish, Portuguese and Hindi (Language in web). In Hindi, the CV's own headings (cv.doc.*) stay in English: they go into its PDF, whose font (Noto Sans) has no Devanagari, and CVs in India are mostly written in English.
-
Where the texts live:
web/src/main/resources/i18n/web.properties(pages, form validation, status and rejection reason names), and each module's error messages next to its code in<module>/src/main/resources/i18n/<module>-errors.properties, undererror.<code>(e.g.error.JOBS-001). Each has one file per language, e.g.web_ro.properties. English is the file without a suffix, and the fallback for everything. -
In templates:
th:text="#{applications.title}"; with arguments#{application.added(${date})}; an enum value#{${'status.' + status}}. Validation messages refer to a key:@NotBlank(message = "{validation.profile.name.required}"). The modules' exceptions carry arguments for their message's{0},{1}... - Adding a text: add the key to the English file and to every translation. MessageBundlesTests fails if a translation is missing a key, or if an error code has no message.
-
Adding a language: a constant in
Language, a file per bundle, and and a folder inextension/_locales. -
Adding a module with error codes: its
i18n/<module>-errorsfiles, plus the bundle inspring.messages.basename(application.properties) and inMessageBundlesTests. -
Apostrophes: write
’, not'. In a message with{0}, Java'sMessageFormattreats'as a quote character and swallows text. - Logs stay in English: they're for whoever runs the app, not for users.
./mvnw verify runs everything. On every pull request, every push to main and every release tag, GitHub Actions runs one workflow, CI, whose jobs each wait for what they need:
| Job | What | After |
|---|---|---|
build |
Compiles every module with Error Prone and NullAway, checks the imports and the pages' JavaScript (ESLint), builds the CSS, packages the jar | |
test |
All the tests, with what they cover (-Pcoverage, JaCoCo) |
build |
sonar |
SonarCloud's analysis, with that coverage, and its quality gate's verdict. Skipped on pull requests from forks, which GitHub gives no secrets (SONAR_TOKEN): their code is analyzed once merged, on main (see below) |
test |
docker |
Builds the image | build |
publish |
On main and tags: publishes the image |
test, docker
|
release |
On tags: publishes the release (below) | publish |
dependency-review |
On pull requests: the dependencies they add, failing on a high-severity vulnerability | |
codeql |
Code scanning of the Java, the JavaScript and the workflows |
CodeRabbit reviews each pull request (a GitHub App, so its check shows beside the workflow's rather than in it), and Dependabot keeps the dependencies and the actions up to date. The "Protect Main" ruleset (.github/rulesets) makes a pull request wait for the build, the tests, the dependency review, the image, SonarCloud's quality gate and CodeQL, and for the code owner's approval (CODEOWNERS). GitHub doesn't let anyone approve their own pull request, so the owner's go through the admin bypass, which skips the checks too: merge those only once they're green. A pull request from a fork never gets SonarCloud's check, as its run has no SONAR_TOKEN: the owner reviews its code with the other checks green, merges it through the same bypass, and main's run analyzes it right after; a quality gate failing there is fixed in a pull request of the owner's. The file doesn't apply itself; after changing it, run gh api -X PUT repos/CRV96/jobwarden/rulesets/26456384 --input .github/rulesets/protect-main.json. See SECURITY.md for reporting a vulnerability.
Each kind of test has one place:
| Test | Where | Example |
|---|---|---|
| Unit tests (plain JUnit + Mockito) | the module itself | JobWardenLoggerTests, CurrentUserTests |
Controller tests (@WebMvcTest) |
web and capture, next to the controller |
ApplicationControllerTests, CaptureControllerTests, CaptureExceptionHandlerTests |
Service tests against a real database (@ApplicationModuleTest) |
app, in the module's package, e.g. app/src/test/java/com/jobwarden/jobs/
|
ApplicationServiceTests |
| Whole application and module boundaries | app |
ModularityTests |
| The code's conventions (ArchUnit) | app |
ConventionsTests |
| What the AI assistant reads: the tool list and each kind of request, in characters, with budgets | mcp |
McpBudgetTests, which prints the table and writes it to mcp/target/mcp-budget.tsv
|
Why database tests live in app: the migrations only run there, and jobs' tables reference identity's. @ApplicationModuleTest still starts just the one module, which also proves the module doesn't depend on other modules' beans.
web and capture can't see the real application class, so each has a small *TestApplication in its test sources for @WebMvcTest to start from.
What changed from one release to the next is in CHANGELOG.md: each change adds its line under Unreleased.
The app and the extension share one version: the Maven projects' (<version> in every pom.xml) and version in
extension/manifest.json; VersionTests
fails when they differ. Maven writes it into jobwarden.version, which Settings, the MCP server and the extension
show.
To release a version:
- Set it everywhere:
./mvnw versions:set -DnewVersion=1.0.2 -DgenerateBackupPoms=false, and"version": "1.0.2"in the manifest. - Commit, then tag the commit and push the tag:
git tag v1.0.2 && git push origin v1.0.2.
The tag's run of CI checks that the tag, the
Maven projects and the manifest say the same, builds and tests, publishes the tag's image, then a GitHub release with
the app's jar, the extension's zip, a compose.yaml for that version, and notes made from the pull requests since the
last release. Each is attested as built from the tag
(SECURITY.md shows how to
verify it).
These pages are docs/wiki/ in the repository: change them in a pull request like the code. On every push to main,
the Wiki workflow copies them to the GitHub wiki, replacing what was there:
an edit made on the wiki itself doesn't last. A page links to another by its name without .md, e.g.
[Updating](https://github.com/CRV96/jobwarden/blob/main/Updating); _Sidebar.md is the menu beside every page.
JobWarden · Releases · Discord · Suggest a feature · Report a bug · MIT License