These are the rules a reviewer checks a change to Wicket against, in detail. CONTRIBUTING.md in the repository has them in short, with the ASF’s rules on licensing and generative AI tools.
Code format
| Rule | Value |
|---|---|
| Indentation | Tabs, shown as 4 spaces |
| Braces | On a line of their own, for classes, methods and blocks |
| Line length | At most 100 characters |
| Imports | One per class, no *, except static imports in tests |
| Formatter |
wicket-eclipse-settings/files/org.eclipse.jdt.core.prefs; see Set up your IDE
|
The build does not check the format, and the code is formatted by hand. Match the file you edit, turn off formatting on save, and do not reformat lines you did not change.
License header
Every new file starts with the Apache License header, as a comment in the syntax of the file: Java, JavaScript, CSS, HTML, .properties, pom.xml. Copy it from a file of the same type. The full build checks the headers with Apache RAT and fails on a file without one.
Language
Everything is in English: names, comments, Javadoc, messages, commit messages and branch names. A new message key goes into the default bundle, such as Application.utf8.properties; the translated bundles, such as Application_nl.utf8.properties, are written by native speakers.
Tests
- A test class name ends in
Test, such asUrlRendererTest. Maven runs only classes named*Test.java: a class namedUrlRendererTestsorTestUrlRenderercompiles but never runs. - A module with a
-testscompanion keeps its tests there: the tests ofwicket-coreare inwicket-core-tests, those ofwicket-cdiinwicket-cdi-tests. Other modules, such aswicket-utilandwicket-extensions, keep their tests in their ownsrc/test/java. Follow the module you work in, and put a new test next to the existing test of the same class. - The HTML markup of a test page sits next to its Java class in
src/test/java, not insrc/test/resources. - Tests use JUnit 5. For pages and components, extend
WicketTestCase, which gives you aWicketTesterastester. - JavaScript tests are QUnit tests in
src/test/js/ofwicket-coreandwicket-extensions; see Run the JavaScript tests.
Javadoc and comments
- Public classes and methods have Javadoc that says what they do with the values they get, not only what they return.
- A new public class, method or field gets an
@sincetag with the first release it appears in:@since 12.0.0onmaster. - Comments explain why, not what. Most code needs none; the reasoning for a change goes into the commit message.
Changes to the API
A change to a public class or method can break applications that use it; API compatibility explains the rules below. On master, it needs a reason in the commit message, and where the old method can stay next to the new one, deprecate the old one with @Deprecated instead of removing it. On the release branches, such as wicket-11.x, the build fails on a change that breaks compatibility. A change that applications must react to also gets a section in migration-to-<major>.md in the root of the repository and, where it is mechanical, an OpenRewrite recipe in wicket-migration. Ask on the issue before you change public API.
poms
The build checks the order in every pom.xml: sections in the standard Maven order, and dependencies sorted by scope, then group id, then artifact id. A module pom.xml names no versions; they are set as properties in the root pom.xml.
Commit messages
| Part | Content |
|---|---|
| First line | What the change does, in plain words, without the issue number. |
| Body | What the behaviour was, why that was wrong, what it is now, and what an application that relied on the old behaviour notices. |
| Issue |
GitHub issue #<number> on a line of its own; a Jira key such as WICKET-7165 for an issue from Jira. |
| Tools |
Generated-by: <name of tool> <version> when a generative AI tool wrote part of the change, as the ASF asks. |
Keep commits focused: one logical change per commit, and never formatting mixed with a fix. No “WIP”, “fix stuff” or “review comments” commit is left in a pull request when it is merged. During the review you may push fixes as separate commits; before the merge they are squashed into the commit they belong to. The committer who merges your pull request tells you whether to squash yourself or whether they squash when merging.
Never force-push to a branch in apache/wicket itself; the repository refuses it. Force-pushing your own pull request branch to clean it up is fine.
Security
A suspected vulnerability goes to security@apache.org, never into an issue, pull request, commit message or branch name. SECURITY.md describes what counts as a vulnerability in Wicket, and Wicket’s security model the idea behind it.