This is an automated email from the ASF dual-hosted git repository. dashorst pushed a commit to branch contribute-wicket-code in repository https://gitbox.apache.org/repos/asf/wicket-site.git
commit b503e32ed48603bbd18fb112f7d3c788c7393920 Author: Martijn Dashorst <[email protected]> AuthorDate: Thu Nov 19 16:06:05 2026 +0100 Add a tutorial and explanations to the contributor pages for Wicket's code CONTRIBUTING.md in apache/wicket now holds only the rules and links to wicket-pull-request, wicket-build, wicket-ide and wicket-conventions for everything that teaches or explains. Those four URLs stay. The Diataxis set for Wicket's code gets what it lacked: - Your first pull request (tutorial): issue #1950 from claim to pull request, with the test, the one-line fix, and the test run that still fails until wicket-request is installed. - Why most tests live in another module, Why fixes go to master first, API compatibility (japicmp's baseline is the .0.0 release of the branch's line, so it only checks the release branches) and Wicket's security model, which points to SECURITY.md instead of copying it. Set up your IDE adds VS Code with a launch configuration for StartExamples, says per IDE whether a test run needs an install first, and asks to turn off format-on-save and never reformat a whole file. The M2E Settings advice goes: no IDE picks up the formatter by itself. The pull request page states the two-week claim rule and links CONTRIBUTING.md. Versions of Java, Maven, Node and Chrome, and the JavaScript test setup, are linked to README.md, the GitHub workflow and JAVASCRIPTTESTING.md instead of copied, because the site is not versioned per branch. The tutorial's steps were run as written in a clone of master. Co-Authored-By: Claude Opus 5.5 <[email protected]> --- _contribute/wicket-api-compatibility.md | 27 ++++++ _contribute/wicket-build.md | 25 ++--- _contribute/wicket-conventions.md | 13 +-- _contribute/wicket-first-pull-request.md | 154 +++++++++++++++++++++++++++++++ _contribute/wicket-ide.md | 83 +++++++++++++---- _contribute/wicket-master-first.md | 32 +++++++ _contribute/wicket-pull-request.md | 14 +-- _contribute/wicket-security-model.md | 27 ++++++ _contribute/wicket-test-modules.md | 29 ++++++ contribute/index.md | 2 +- 10 files changed, 360 insertions(+), 46 deletions(-) diff --git a/_contribute/wicket-api-compatibility.md b/_contribute/wicket-api-compatibility.md new file mode 100644 index 00000000..506a8b1c --- /dev/null +++ b/_contribute/wicket-api-compatibility.md @@ -0,0 +1,27 @@ +--- +title: API compatibility +type: explanation +topic: wicket +summary: Which changes to Wicket's public API are allowed where, why the build checks them only on the release branches, and what a breaking change owes its users. +order: 80 +--- + +## Applications compile against Wicket + +Every public class, method and field of Wicket is API: some application calls it, extends it or overrides it. When a method changes its parameters or disappears, applications that use it no longer compile. Worse, an application that was compiled against the old version and runs with the new one fails only at runtime, with a `NoSuchMethodError` at the moment the code is reached. Such a change is called binary incompatible. + +## Breaking changes wait for a major release + +Within a release line, an upgrade must be safe: going from 11.0.0 to 11.1.0 must not break the code of an application. Changes that break the API are only made in a new major release, on `master`. With a major release [every three months]({{ site.baseurl }}/versions/#release-policy), a needed change does not wait long. + +Allowed on `master` does not mean free. Every breaking change costs every application an edit when it upgrades. So a change to public API needs a reason in its commit message, and where the old method can stay next to the new one, the old one is deprecated with `@Deprecated` and removed in a later major release, instead of removed at once. + +## japicmp checks the release branches + +The build compares every module with the first release of its line, the `.0.0` release, using the [japicmp](https://siom79.github.io/japicmp/) plugin, and fails on a binary incompatible change. The version to compare with is derived from the version of the branch: on `wicket-11.x`, whose version is `11.x.y-SNAPSHOT`, it is `11.0.0`. + +On `master`, that release does not exist yet: the first release of the line under development is the one being prepared. japicmp finds nothing to compare with and checks nothing. This is what allows the breaking changes of a new major release, and it means the build on `master` does not tell you when your change breaks the API. You find out when someone tries to cherry-pick it to a release branch, and the build there fails. A change that touches public API is therefore worth a question o [...] + +## A migration path for every break + +A change that breaks code or changes what a running application does gets a section in the migration guide of the release, `migration-to-<major>.md` in the root of the repository, in the same pull request. Where the change is mechanical, such as a renamed method, it also gets an [OpenRewrite](https://docs.openrewrite.org/) recipe in the `wicket-migration` module, so that applications can apply it automatically. Users read the guide when they upgrade; it is how they learn about the change [...] diff --git a/_contribute/wicket-build.md b/_contribute/wicket-build.md index 651f0ec3..2084aa01 100644 --- a/_contribute/wicket-build.md +++ b/_contribute/wicket-build.md @@ -3,17 +3,16 @@ title: Build and test Wicket type: howto topic: wicket summary: Build Wicket from source with Maven, run one test or all of them, run the JavaScript tests and the examples, and use your own build. -order: 20 +order: 30 --- {% assign next = site.data.releases.lines | where: "status", "boarding" | first %} -{% assign lts = site.data.releases.lines | where: "status", "lts" | first %} Wicket is a Maven project of about 35 modules, one folder each, built together from the `pom.xml` in the root of the repository. You run every command on this page in that root folder, the `wicket` folder of your clone. ## What you need -- **JDK 21 or newer.** `master` and the current release line need Java 21{% if lts %}; `wicket-{{ lts.series }}.x` needs Java 17{% endif %}. GitHub tests with Java 21, 25 and 26. -- **Maven 3.9.** The Maven inside your IDE is not available on the command line, so [install Maven](https://maven.apache.org/install.html) as well. +- **A JDK** of at least the Java version that [README.md](https://github.com/apache/wicket/blob/master/README.md#javaapplication-server-requirements) names under "Java/Application server requirements"; newer is fine. The build uses the version set in `maven.compiler.release` in the root `pom.xml`, and the GitHub workflow, [`.github/workflows/maven.yml`](https://github.com/apache/wicket/blob/master/.github/workflows/maven.yml), lists the JDKs it tests with. +- **Maven** on the command line. The Maven inside your IDE is usually not available there, so [install Maven](https://maven.apache.org/install.html) as well, a current release; the GitHub workflow names the version it uses. - **Git**, and about 2 GB of free disk space for the clone, the build results and the downloaded libraries. Check that Maven runs with the right Java: @@ -22,7 +21,7 @@ Check that Maven runs with the right Java: mvn -v ``` -The output names the Maven version and, on the line `Java version:`, the JDK. If that is older than 21, set the `JAVA_HOME` environment variable to the folder of your JDK 21. +The output names the Maven version and, on the line `Java version:`, the JDK. If that JDK is too old, set the `JAVA_HOME` environment variable to the folder of a newer one. ## Build everything @@ -30,13 +29,15 @@ The output names the Maven version and, on the line `Java version:`, the JDK. If mvn install -DskipTests -Pfast ``` -`install` compiles every module, packages it as a jar and copies the jar to your local Maven repository, the folder `.m2/repository` in your home folder. `-DskipTests` skips the tests, and `-Pfast` skips the javadoc, the source jars and the license header check. The first build downloads about 450 MB of libraries and takes a few minutes; later builds take one to two minutes. +`install` compiles every module, packages it as a jar and copies the jar to your local Maven repository, the folder `.m2/repository` in your home folder. `-DskipTests` skips the tests, and `-Pfast` skips the javadoc, the source jars and the license header check. The first build downloads several hundred MB of libraries and takes a few minutes; later builds are faster. The build ends with `BUILD SUCCESS` and a list of the modules with their times. The jars are now in your local repository, version {% if next %}`{{ next.version }}-SNAPSHOT`{% else %}the `-SNAPSHOT` version in the root `pom.xml`{% endif %} on `master`. A snapshot is a version under development, not a release. ## Run one test {#run-one-test} -The tests of `wicket-core` are in a separate module, `wicket-core-tests`, and so are some tests of classes in other modules: `UrlRendererTest`, for `UrlRenderer` in `wicket-request`, is one. The test can also be in another package than the class, so search for it by name, as in [Send a pull request]({{ site.baseurl }}/contribute/wicket-pull-request.html#change). A test in another module uses the module you changed from your local Maven repository, not from your working folder. So install [...] +The tests of `wicket-core` are in a separate module, `wicket-core-tests`, and so are some tests of classes in other modules: `UrlRendererTest`, for `UrlRenderer` in `wicket-request`, is one. The test can also be in another package than the class, so search for it by name, as in [Send a pull request]({{ site.baseurl }}/contribute/wicket-pull-request.html#change). A test in another module uses the module you changed from your local Maven repository, not from your working folder. So install [...] + + ```shell mvn install -DskipTests -Pfast -pl wicket-request @@ -51,7 +52,7 @@ When the test is in the same module as the code, as for most of `wicket-util` an mvn verify -pl wicket-extensions -Dtest=AutoCompleteTest ``` -To run one method of a test class, add its name: `-Dtest=UrlRendererTest#test1`. The [conventions]({{ site.baseurl }}/contribute/wicket-conventions.html#tests) say where a new test goes and how to name it. +To run one method of a test class, add its name: `-Dtest=UrlRendererTest#renderFullUrlWithRelativeArgument`. The [conventions]({{ site.baseurl }}/contribute/wicket-conventions.html#tests) say where a new test goes and how to name it. Instead of installing first, `-am` ("also make") builds the modules the test module depends on from your working folder. It then looks for the test in each of those modules too, so it needs a second option: @@ -67,9 +68,9 @@ The JavaScript tests run in a headless Chrome and are off unless you ask for the mvn test -pl testing/wicket-js-tests -Pjs-test ``` -The first run downloads Node.js into the `testing/wicket-js-tests` folder and Chrome into `.cache/puppeteer` in your home folder, which takes a while. On Linux, that Chrome needs the libraries of a normal Chrome installation; installing Google Chrome or Chromium is the easiest way to get them. The tests read the `.js` files from your working folder, so you do not need to install anything first. +The tests read the `.js` files from your working folder, so you do not need to install anything first. The first run downloads the tools the tests need and takes a while; on Linux, the browser needs some system libraries. -The tests for the scripts of `wicket-core` are in `wicket-core/src/test/js/`, those for `wicket-extensions` in `wicket-extensions/src/test/js/`. A script without its own tests, such as `wicket-autocomplete.js`, is only checked by JSHint for mistakes. To add tests for it, add a `<name>-test.js` and a `<name>.html` page next to the existing ones in `wicket-extensions/src/test/js/`, and list them in `testing/wicket-js-tests/Gruntfile.js`: the test file under `extensionsTestsJs`, and the pag [...] +[JAVASCRIPTTESTING.md](https://github.com/apache/wicket/blob/master/JAVASCRIPTTESTING.md) in the repository is the reference for these tests: what it downloads and which libraries it needs, where the tests are, how to add a test page, and how to run the tests faster without Maven. Every script is checked by JSHint, also the scripts without tests of their own, such as `wicket-autocomplete.js`. When you fix such a script, say in the pull request how you tested the fix. ## Run the examples @@ -80,7 +81,7 @@ mvn install -DskipTests -Pfast mvn jetty:run -pl wicket-examples ``` -When the output shows a line with `Started oejs.Server`, open <http://localhost:8080>. Stop the server with Ctrl+C. To run the examples from your IDE, see [Set up your IDE]({{ site.baseurl }}/contribute/wicket-ide.html#examples). +When Jetty reports that the server started, open <http://localhost:8080>. Stop the server with Ctrl+C, and install again after each change. To run the examples from your IDE, without installing, see [Set up your IDE]({{ site.baseurl }}/contribute/wicket-ide.html). ## Run the full build @@ -110,7 +111,7 @@ This is a quick way to check a fix in a [quickstart]({{ site.baseurl }}/start/qu ## When the build fails -- **`release version 21 not supported`**: Maven runs with an older Java. Check `mvn -v` and set `JAVA_HOME`. +- **`release version … not supported`**: Maven runs with an older Java than the build needs. Check `mvn -v` and set `JAVA_HOME`. - **`Counter(s) UNAPPROVED exceeded minimum or maximum values`**: a file you added has no license header. In `target/rat.txt` in the root folder, the files without one start with a `!`. Copy the header from a file of the same type. - **A test fails that has nothing to do with your change**: check whether it also fails on `master`. The [build status of master](https://github.com/apache/wicket/actions?query=branch%3Amaster) shows whether it is broken there. If it is not, mention the failing test in your issue. - **`No tests matching pattern`**: the test name after `-Dtest` does not exist in the modules you build. Check the module after `-pl` and the spelling of the class. diff --git a/_contribute/wicket-conventions.md b/_contribute/wicket-conventions.md index 413a21b4..285e69c2 100644 --- a/_contribute/wicket-conventions.md +++ b/_contribute/wicket-conventions.md @@ -3,11 +3,12 @@ title: Code conventions type: reference topic: wicket summary: The rules a change to Wicket's code follows, from the code format and license header to tests, Javadoc and commit messages. -order: 40 +order: 50 --- {% assign next = site.data.releases.lines | where: "status", "boarding" | first %} +{% assign current = site.data.releases.lines | where: "status", "current" | first %} -These are the rules a reviewer checks a change to Wicket against. The repository has its own guide for contributors, [CONTRIBUTING.md](https://github.com/apache/wicket/blob/master/CONTRIBUTING.md). +These are the rules a reviewer checks a change to Wicket against, in detail. [CONTRIBUTING.md](https://github.com/apache/wicket/blob/master/CONTRIBUTING.md) in the repository has them in short, with the ASF's rules on licensing and generative AI tools. ## Code format @@ -19,7 +20,7 @@ These are the rules a reviewer checks a change to Wicket against. The repository | 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]({{ site.baseurl }}/contribute/wicket-ide.html#the-code-format) | -The build does not check the format. Match the file you edit, and do not reformat lines you did not change. +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 @@ -45,7 +46,7 @@ Everything is in English: names, comments, Javadoc, messages, commit messages an ## Changes to the API -A change to a public class or method can break applications that use it. 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-<version>.md` in the root of the repository. +A change to a public class or method can break applications that use it; [API compatibility]({{ site.baseurl }}/contribute/wicket-api-compatibility.html) 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{% if current %}, such as `wicket-{{ current.series }}.x`{% endif %}, the build fails on a change that breaks compa [...] ## poms {#poms} @@ -58,10 +59,10 @@ The build checks the order in every `pom.xml`: sections in the standard Maven or | First line | What the change does, as a plain sentence. No issue number and no prefix like `fix:`. | | 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>` when a generative AI tool wrote part of the change, as the [ASF asks](https://www.apache.org/legal/generative-tooling.html). | +| Tools | `Generated-by: <name of tool> <version>` when a generative AI tool wrote part of the change, as the [ASF asks](https://www.apache.org/legal/generative-tooling.html). | A commit that is already pushed is not changed: no amend, rebase or force-push. Correct it with a new commit, and bring a branch up to date by merging `master` into it. ## Security -A suspected vulnerability goes to [email protected], never into an issue, pull request, commit message or branch name. [SECURITY.md](https://github.com/apache/wicket/blob/master/SECURITY.md) describes what counts as a vulnerability in Wicket. +A suspected vulnerability goes to [email protected], never into an issue, pull request, commit message or branch name. [SECURITY.md](https://github.com/apache/wicket/blob/master/SECURITY.md) describes what counts as a vulnerability in Wicket, and [Wicket's security model]({{ site.baseurl }}/contribute/wicket-security-model.html) the idea behind it. diff --git a/_contribute/wicket-first-pull-request.md b/_contribute/wicket-first-pull-request.md new file mode 100644 index 00000000..5648a703 --- /dev/null +++ b/_contribute/wicket-first-pull-request.md @@ -0,0 +1,154 @@ +--- +title: Your first pull request +type: tutorial +topic: wicket +summary: Fix a real bug in Wicket from start to end, with a failing test, the fix, the right way to run the tests, and the pull request. +order: 10 +--- + +In this tutorial you fix [issue #1950](https://github.com/apache/wicket/issues/1950): `UrlRenderer#renderFullUrl` forgets the fragment of a URL, the part after `#`. You write a test that shows the bug, fix it with one line, and send the fix to the Wicket project as a pull request. + +You need a GitHub account, Git, a JDK and Maven on the command line. [Build and test Wicket]({{ site.baseurl }}/contribute/wicket-build.html#what-you-need) says which versions, and how to check them. You do not need to know Wicket. + +## 1. Claim the issue + +Open [issue #1950](https://github.com/apache/wicket/issues/1950) and write a comment that you are working on it. If somebody else already claimed it less than two weeks ago, pick another [`good first issue`](https://github.com/apache/wicket/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) and follow the same steps with that issue. + +## 2. Get the code + +Fork apache/wicket on GitHub with the Fork button. Then clone your fork, add the Wicket repository as `upstream`, and create a branch from Wicket's `master`: + +```shell +git clone https://github.com/<your-account>/wicket.git +cd wicket +git remote add upstream https://github.com/apache/wicket.git +git fetch upstream +git checkout -b keep-url-fragment upstream/master +``` + +## 3. Build Wicket + +Build every module once, without running the tests: + +```shell +mvn install -DskipTests -Pfast +``` + +The first time, Maven downloads the libraries Wicket uses, which takes a few minutes. The build ends with `BUILD SUCCESS`. It has put a jar of every module in your local Maven repository, the folder `.m2/repository` in your home folder. + +## 4. Write a test that shows the bug + +`UrlRenderer` is in the module `wicket-request`, but its test is in another module, `wicket-core-tests`. Open `wicket-core-tests/src/test/java/org/apache/wicket/core/request/cycle/UrlRendererTest.java` and add this method inside the class, below the method `renderFullUrlWithRelativeArgument`: + +```java + @Test + void renderFullUrlKeepsFragment() + { + Url baseUrl = Url.parse("one/two/three"); + baseUrl.setProtocol("http"); + baseUrl.setHost("www.example.com"); + baseUrl.setPort(8888); + UrlRenderer renderer = new UrlRenderer(new MockWebRequest(baseUrl)); + renderer.setBaseUrl(baseUrl); + String fullUrl = renderer.renderFullUrl(Url.parse("../four#section")); + assertEquals("http://www.example.com:8888/one/four#section", fullUrl); + } +``` + +Wicket's code is indented with tabs, so use tabs here too. Run the new test: + +```shell +mvn verify -pl wicket-core-tests -Dtest=UrlRendererTest#renderFullUrlKeepsFragment +``` + +The test fails, and Maven shows why: + +```text +expected: <http://www.example.com:8888/one/four#section> but was: <http://www.example.com:8888/one/four> +``` + +This is the bug: the `#section` is gone. + +## 5. Fix the bug + +Open `wicket-request/src/main/java/org/apache/wicket/request/UrlRenderer.java` and find the method `renderFullUrl`. For a relative URL, it resolves the URL against the base URL: + +```java + Url base = new Url(baseUrl); + base.resolveRelative(url); +``` + +`resolveRelative` takes over the path and the query parameters of `url`, but not its fragment. Add a line that copies the fragment as well: + +```java + Url base = new Url(baseUrl); + base.resolveRelative(url); + base.setFragment(url.getFragment()); +``` + +## 6. Run the test again + +Run the same test: + +```shell +mvn verify -pl wicket-core-tests -Dtest=UrlRendererTest#renderFullUrlKeepsFragment +``` + +It still fails. You changed `wicket-request`, but you only built `wicket-core-tests`, so Maven used the `wicket-request` jar from your local repository: the one you built in step 3, without your fix. Install `wicket-request` first, then run the test: + +```shell +mvn install -DskipTests -Pfast -pl wicket-request +mvn verify -pl wicket-core-tests -Dtest=UrlRendererTest#renderFullUrlKeepsFragment +``` + +Now the test passes. Run all tests of the class, to see that the fix breaks nothing else in it: + +```shell +mvn verify -pl wicket-core-tests -Dtest=UrlRendererTest +``` + +## 7. Run the full build + +Build and test everything, the way GitHub does it for every pull request: + +```shell +mvn clean verify -Pjs-test +``` + +This takes a while: on a laptop, count on a quarter of an hour or more. It has to end with `BUILD SUCCESS`. + +## 8. Commit + +Add the two files and commit: + +```shell +git add wicket-request/src/main/java/org/apache/wicket/request/UrlRenderer.java +git add wicket-core-tests/src/test/java/org/apache/wicket/core/request/cycle/UrlRendererTest.java +git commit +``` + +Git opens a text editor. Write this message, save and close the editor: + +```text +Keep the fragment in UrlRenderer.renderFullUrl + +renderFullUrl dropped the fragment of a relative URL, while +renderRelativeUrl kept it, so a full URL to "page#section" pointed to +"page". The fragment is now copied to the resolved URL as well. + +GitHub issue #1950 +``` + +## 9. Open the pull request + +Push your branch to your fork: + +```shell +git push -u origin keep-url-fragment +``` + +The output of `git push` shows a link to create a pull request; open it. Check that the base repository is `apache/wicket` and the base branch is `master`. Write `Fixes #1950` in the description, with a sentence on how you tested the fix, and create the pull request. + +GitHub now runs the full build for your pull request, and a committer reviews it. You have sent your first pull request to Wicket. + +For your next change, [Send a pull request to Wicket]({{ site.baseurl }}/contribute/wicket-pull-request.html) has the same steps in short, with what to do during the review. [Why most tests live in another module]({{ site.baseurl }}/contribute/wicket-test-modules.html) explains what happened in step 6. diff --git a/_contribute/wicket-ide.md b/_contribute/wicket-ide.md index 06247790..929af63b 100644 --- a/_contribute/wicket-ide.md +++ b/_contribute/wicket-ide.md @@ -2,49 +2,92 @@ title: Set up your IDE type: howto topic: wicket -summary: Open Wicket's source in IntelliJ IDEA, Eclipse or NetBeans, use Wicket's code format, and run tests and the examples from the IDE. -order: 30 +summary: Open Wicket's source in IntelliJ IDEA, Eclipse, VS Code or NetBeans, keep its hand-made format, and run tests and the examples from the IDE. +order: 40 --- This page sets up your IDE to work on Wicket itself. For IDE plugins that help you build applications with Wicket, see [Add Wicket support to your IDE]({{ site.baseurl }}/docs/ide-plugins.html) in the user guide. -Wicket is a Maven project, and every Java IDE opens it as one. Build it once on the command line first, as in [Build and test Wicket]({{ site.baseurl }}/contribute/wicket-build.html), so that the libraries are already downloaded. +Wicket is a Maven project, and every Java IDE opens it as one. Open the root folder of your clone, so that the IDE sees all modules. Build once on the command line first, as in [Build and test Wicket]({{ site.baseurl }}/contribute/wicket-build.html), so that the libraries are already downloaded. ## The code format -Wicket's code uses tabs for indentation, braces on their own line, and lines of at most 100 characters. The exact rules are an Eclipse formatter configuration in the repository, `wicket-eclipse-settings/files/org.eclipse.jdt.core.prefs`. The build does not check the format, so a reviewer will: format only the lines you change, and keep the rest of the file as it is. Reformatting a whole file makes your change hard to review. +Wicket's code uses tabs for indentation, braces on their own line, and lines of at most 100 characters. Set your IDE's Java formatter to these three rules. The exact Eclipse formatter settings are in the repository, in `wicket-eclipse-settings/files/org.eclipse.jdt.core.prefs`, but no IDE picks them up by itself. + +The code is formatted by hand, and no formatter reproduces it exactly. So: + +- Turn off formatting on save. +- Never reformat a whole file. Format only the lines you write, or match the code around them by hand. + +A reformatted file shows hundreds of changed lines in the pull request, and the reviewer cannot find your change between them. It also makes the commit hard to cherry-pick to the older branches, where the same lines look different. + +## Do tests from the IDE need an install? + +Running a test with Maven needs an `mvn install` of the module you changed first, when the test is in another module; [Why most tests live in another module]({{ site.baseurl }}/contribute/wicket-test-modules.html) explains why. In the IDE it depends on how the IDE builds: + +| IDE | Install first? | +|---|---| +| IntelliJ IDEA | No. It compiles the other modules from your working folder. | +| Eclipse | No. Its Maven support resolves the other modules from the workspace. | +| VS Code | No. Its Java language server resolves the other modules from source. | +| NetBeans | Probably yes. NetBeans builds through Maven, so a test may use the installed jar of another module. Install the changed module to be sure. | + +Before you send a pull request, run the tests with Maven anyway, as in [Run one test]({{ site.baseurl }}/contribute/wicket-build.html#run-one-test): that is how GitHub runs them. ## IntelliJ IDEA IntelliJ IDEA Community Edition is enough. 1. Choose **File → Open**, select the `wicket` folder of your clone and open it as a project. IntelliJ reads the Maven modules, which takes a few minutes the first time. -2. In **File → Project Structure → Project**, set the SDK to JDK 21. -3. For the code format, install the plugin **Adapter for Eclipse Code Formatter** from **Settings → Plugins → Marketplace**. In its settings, choose to use the Eclipse code formatter with the configuration file `wicket-eclipse-settings/files/org.eclipse.jdt.core.prefs` from your clone. -4. In **Settings → Editor → Code Style → Java → Imports**, set **Class count to use import with '\*'** to 99, so that IntelliJ writes one import per class, as Wicket's code does. +2. In **File → Project Structure → Project**, set the SDK to the JDK you build with. +3. In **Settings → Editor → Code Style → Java**, set **Tabs and Indents** to use the tab character with size 4, **Wrapping and Braces** to put braces on the next line and the hard wrap at 100, and in **Imports**, **Class count to use import with '\*'** to 99. +4. In **Settings → Tools → Actions on Save**, leave **Reformat code** off. -To format only your changes, use **Code → Reformat Code** with **Only changes uncommitted to VCS**. +The plugin **Adapter for Eclipse Code Formatter** can use `org.eclipse.jdt.core.prefs` instead of step 3. It still reformats whatever you ask it to, so the rules above apply. -### Run a test +Run a test with the green arrow next to the class or a method. To run the examples, open `wicket-examples/src/test/java/org/apache/wicket/examples/StartExamples.java` and run its `main` method; it starts the examples on <http://localhost:8080>. The working directory of the run configuration must be the `wicket-examples` folder, the default. If the examples show only errors about missing files, check it under **Run → Edit Configurations**. -Open the test class and click the green arrow next to the class or a method. IntelliJ compiles the modules of the project from your working folder, so a change in `wicket-request` is used by a test in `wicket-core-tests` without installing it first. Run the test with Maven as well before you send the pull request, as in [Run one test]({{ site.baseurl }}/contribute/wicket-build.html#run-one-test): that is how GitHub runs it. +## Eclipse -### Run the examples {#examples} +Use the Eclipse IDE for Java Developers or for Enterprise Java, which include Maven support. -Open `wicket-examples/src/test/java/org/apache/wicket/examples/StartExamples.java` and run its `main` method. It starts the examples on <http://localhost:8080>, with your code from the working folder. The working directory of the run configuration must be the `wicket-examples` folder, which is the default; if the examples show only errors about missing files, check it under **Run → Edit Configurations**. +1. Choose **File → Import → Maven → Existing Maven Projects**, select the `wicket` folder of your clone, and import all projects. Every module becomes a project. +2. Add the JDK you build with under **Window → Preferences → Java → Installed JREs**. +3. Under **Window → Preferences → Java → Code Style → Formatter**, create a profile with tab indentation of size 4, braces on the next line, and a maximum line width of 100. +4. Under **Window → Preferences → Java → Editor → Save Actions**, leave **Perform the selected actions on save** off. -## Eclipse +Run a test with **Run As → JUnit Test** on the test class. **Run As → Java Application** on `StartExamples` in the `wicket-examples` project starts the examples; Eclipse uses the project folder as working directory. -Use the Eclipse IDE for Java Developers or for Enterprise Java, which include Maven support. +## VS Code -1. Before you import, install **M2E Settings** from the Eclipse Marketplace (**Help → Eclipse Marketplace**). It applies Wicket's code format to every module while they are imported. -2. Choose **File → Import → Maven → Existing Maven Projects**, select the `wicket` folder of your clone, and import all projects. -3. Set a JDK 21 as installed JRE under **Window → Preferences → Java → Installed JREs**. +1. Install the **Extension Pack for Java** from the Extensions view. +2. Choose **File → Open Folder** and open the `wicket` folder of your clone. The Java extension reads the Maven modules, which takes a few minutes the first time. +3. Make sure **Editor: Format On Save** is off in the settings. -To format only your changes, set **Window → Preferences → Java → Editor → Save Actions** to format edited lines. +Run tests from the Testing view or with the run icon next to a test. -Run a test with **Run As → JUnit Test** on the test class, and the examples with **Run As → Java Application** on `StartExamples` in the `wicket-examples` project. +A Java program in VS Code starts in the root folder, but `StartExamples` needs `wicket-examples` as working directory. Create `.vscode/launch.json` in the root folder of your clone with this content, and start **StartExamples** from the **Run and Debug** view: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "java", + "name": "StartExamples", + "request": "launch", + "mainClass": "org.apache.wicket.examples.StartExamples", + "projectName": "wicket-examples", + "cwd": "${workspaceFolder}/wicket-examples" + } + ] +} +``` + +Git ignores the `.vscode` folder in the Wicket repository, so the file stays on your computer. ## NetBeans -NetBeans opens Maven projects directly: **File → Open Project** and select the `wicket` folder. NetBeans cannot read Eclipse formatter files, so set the format by hand under **Tools → Options → Editor → Formatting** for Java: tabs with a size of 4, braces on a new line, and a right margin of 100. +Choose **File → Open Project**, select the `wicket` folder of your clone and check **Open Required Projects**. Set the format under **Tools → Options → Editor → Formatting** for Java: tabs with a size of 4, braces on a new line, and a right margin of 100. + +Run a test with **Test File** and the examples with **Run File** on `StartExamples`. Install the modules you changed first, as in the table above. diff --git a/_contribute/wicket-master-first.md b/_contribute/wicket-master-first.md new file mode 100644 index 00000000..2f56b858 --- /dev/null +++ b/_contribute/wicket-master-first.md @@ -0,0 +1,32 @@ +--- +title: Why fixes go to master first +type: explanation +topic: wicket +summary: Why every pull request targets master, how a fix reaches the release lines afterwards, and who decides which lines get it. +order: 70 +--- +{% assign next = site.data.releases.lines | where: "status", "boarding" | first %} +{% assign current = site.data.releases.lines | where: "status", "current" | first %} +{% assign lts = site.data.releases.lines | where: "status", "lts" | first %} + +## Several lines at once + +Wicket releases a new major version [every three months]({{ site.baseurl }}/versions/#release-policy), and keeps a long-term support line next to it. So at any time several versions get releases: {% if next %}Wicket {{ next.series }} is being developed on `master`, {% endif %}{% if current %}Wicket {{ current.series }} is the current release, maintained on `wicket-{{ current.series }}.x`, {% endif %}{% if lts %}and Wicket {{ lts.series }} is the LTS, maintained on `wicket-{{ lts.series } [...] + +## Newest first + +A fix starts on `master` and is then copied down to the older branches it applies to. Copying a single commit from one branch to another is called cherry-picking. + +The other direction goes wrong in a way nobody notices. A fix made on `wicket-{% if lts %}{{ lts.series }}{% else %}10{% endif %}.x` alone is gone again in the next major release, and the users who upgrade get the bug back. When every fix starts on `master`, the newest line has all of them by construction, and only the copies to older lines need checking. + +That is also why GitHub runs the build only for pull requests against `master`: it is the branch every change passes through. + +## Committers decide which lines get a fix + +Whether a fix goes to the older lines is a decision, not a rule. A fix that changes behaviour applications may rely on can be right for the next major release and wrong for a patch release of the LTS, whose users expect an upgrade to change nothing but the bug. The code may also have moved: a fix on `master` sometimes does not apply to an older branch, or needs a different change there. And on the release branches the build refuses any change that breaks [API compatibility]({{ site.baseu [...] + +So you send one pull request, against `master`, and say in the issue which versions have the bug. The committers decide which lines get the fix, and cherry-pick it after the merge. + +## History that is not rewritten + +Pull requests are merged with a merge commit, and commits that are pushed are never changed. A cherry-pick refers to a commit on `master`; reviewers refer to the commits they have read. A rebase or force-push changes those commits into new ones, and the references point to nothing. That is why a branch in review is brought up to date by merging `master` into it, and a mistake is corrected with a new commit on top. Wicket's own branches refuse force pushes. diff --git a/_contribute/wicket-pull-request.md b/_contribute/wicket-pull-request.md index 5a9a4a1f..1c70e950 100644 --- a/_contribute/wicket-pull-request.md +++ b/_contribute/wicket-pull-request.md @@ -3,19 +3,19 @@ title: Send a pull request to Wicket type: howto topic: wicket summary: From an issue to a reviewed pull request against apache/wicket, for your first contribution or your fiftieth. -order: 10 +order: 20 --- {% assign next = site.data.releases.lines | where: "status", "boarding" | first %} {% assign current = site.data.releases.lines | where: "status", "current" | first %} {% assign lts = site.data.releases.lines | where: "status", "lts" | first %} -Wicket's code lives in [apache/wicket](https://github.com/apache/wicket) on GitHub. You change it in your own copy, send the change as a pull request, and a committer, a member of the project who can merge, reviews it. This page takes you through it in order. You need a GitHub account, Git, JDK 21 and Maven 3.9; [Build and test Wicket]({{ site.baseurl }}/contribute/wicket-build.html) says how to check them. +Wicket's code lives in [apache/wicket](https://github.com/apache/wicket) on GitHub. You change it in your own copy, send the change as a pull request, and a committer, a member of the project who can merge, reviews it. This page takes you through it in order; for a first time, the tutorial [Your first pull request]({{ site.baseurl }}/contribute/wicket-first-pull-request.html) goes through the same steps with a real issue. You need a GitHub account, Git, a JDK and Maven; [Build and test W [...] ## 1. Pick or open an issue {#reportbug} Every change starts from an issue in the [issue tracker](https://github.com/apache/wicket/issues). Issues labelled [`good first issue`](https://github.com/apache/wicket/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) are small and need little knowledge of Wicket. -Comment on the issue that you are working on it, so that nobody else starts the same change. Ask your questions there as well: what the expected behaviour is, where the code is, how to test it. The people who answer would rather spend five minutes on a question than review a pull request that went the wrong way. +Comment on the issue that you are working on it, so that nobody else starts the same change. A claim without a pull request lapses after two weeks; if you need more time, say so on the issue. Ask your questions there as well: what the expected behaviour is, where the code is, how to test it. The people who answer would rather spend five minutes on a question than review a pull request that went the wrong way. For a bug you found yourself, [open an issue](https://github.com/apache/wicket/issues/new) first. Say which Wicket version you use, and add a [quickstart]({{ site.baseurl }}/start/quickstart.html), a small project that shows the bug. Issues from before 2026 are in the read-only [Jira archive](https://issues.apache.org/jira/browse/WICKET); search it too. A security problem never goes into an issue: report it [privately]({{ site.baseurl }}/community/#security). @@ -40,7 +40,7 @@ Wicket has a branch for every release line, a major version that still gets rele {% endif %}{% if lts %}| `wicket-{{ lts.series }}.x` | Wicket {{ lts.series }}, long-term support (LTS) | Committers copy fixes here. | {% endif %} -Start from `master`, also when you found the bug in an older version. After the merge, the committers copy the fix to the older branches where it applies; this is called cherry-picking. Say in the issue which versions the bug affects. Branches of versions that no longer get releases are under `archive/`. +Start from `master`, also when you found the bug in an older version. After the merge, the committers copy the fix to the older branches where it applies; this is called cherry-picking. Say in the issue which versions the bug affects. [Why fixes go to master first]({{ site.baseurl }}/contribute/wicket-master-first.html) explains the reasons. Branches of versions that no longer get releases are under `archive/`. Give your branch a name that says what it does: @@ -106,7 +106,7 @@ GitHub issue #<number> The first line says what the change does, in a normal sentence, without the issue number or a prefix like `fix:`. After an empty line, the body says what was wrong, why, and what is different now. The last line refers to the issue. For an issue that came from Jira, keep its key, such as `WICKET-7165`, in the body. -If you used a generative AI tool to write the change, say so in a last line such as `Generated-by: <name of tool>`, as the [ASF asks](https://www.apache.org/legal/generative-tooling.html). +If you used a generative AI tool to write the change, say so in a last line such as `Generated-by: <name of tool> <version>`, as the [ASF recommends](https://www.apache.org/legal/generative-tooling.html). You stay responsible for every line of it. Check which files you changed, add them, and commit: @@ -131,13 +131,13 @@ GitHub does not accept your password here. Sign in with the [GitHub CLI or a per GitHub then shows a button to compare and open a pull request. Check that the base repository is `apache/wicket` and the base branch is `master`. Give the pull request the first line of your commit message as title, and in the description say what changed, how you tested it, and `Fixes #<number>` for the issue. If the work is not finished but you want early feedback, open it as a draft. -GitHub runs the same full build on Java 21, 25 and 26; the result shows at the bottom of the pull request. On your first pull request, a committer may have to approve that run before it starts. +GitHub runs the same full build on several JDKs; the result shows at the bottom of the pull request. On your first pull request, a committer may have to approve that run before it starts. ## 9. Work with the review A reviewer comments on the pull request. Committers are volunteers, so a review can take a few days. If nothing happens for a week, ask for a review in a comment or on the [developers list]({{ site.baseurl }}/community/#dev). -To answer a review, commit on the same branch and push again; the pull request updates itself. Do not rebase, amend or force-push a branch that is already in review: the reviewers have read your earlier commits. To bring the branch up to date with `master`, merge it: +To answer a review, commit on the same branch and push again; the pull request updates itself. Do not rebase, amend or force-push a branch that is already in review: the reviewers have read your earlier commits, and [history is not rewritten]({{ site.baseurl }}/contribute/wicket-master-first.html#history-that-is-not-rewritten). To bring the branch up to date with `master`, merge it: ```shell git fetch upstream diff --git a/_contribute/wicket-security-model.md b/_contribute/wicket-security-model.md new file mode 100644 index 00000000..2d33618a --- /dev/null +++ b/_contribute/wicket-security-model.md @@ -0,0 +1,27 @@ +--- +title: Wicket's security model +type: explanation +topic: wicket +summary: What Wicket as a framework protects against, what it leaves to the deployment, and why a suspected vulnerability is reported privately. +order: 90 +--- + +The full policy is [SECURITY.md](https://github.com/apache/wicket/blob/master/SECURITY.md) in the repository. It says which lines receive security fixes, what a report needs, and in detail what Wicket trusts. This page explains the idea behind it. + +## A framework, not an application + +Wicket runs inside a servlet container, usually behind a proxy, as part of an application that someone deployed. Some protection only the framework can give, because it happens inside Wicket's own code. Other protection only the deployment can give, because only the deployment knows its host names, its proxies and its users. A security model draws the line between the two: what Wicket promises, and what it trusts the deployment to take care of. + +## What Wicket protects + +Wicket promises the things that are in its own hands. Text that a component renders from its model is escaped, so data from users does not become markup in the page; a component that writes model data unescaped by default is a bug in Wicket. Wicket does not serve every file on the classpath as a resource, only those that pass its resource guard. Where an application registers the resource isolation listener, a request from another site cannot invoke a link, a form or an Ajax behaviour on [...] + +## What Wicket trusts + +Other inputs Wicket takes as given. It trusts the host name and port the servlet container reports, because only the deployment knows its own names and can reject the wrong ones. It trusts the markup files of the application, because the developer wrote them, the same way a template engine trusts its templates. It trusts its own page store, because Java deserialization of data from an attacker is never safe. A report that only works when one of these trusted inputs is in an attacker's ha [...] + +Some code is outside the model entirely: deprecated code, which applications should stop using, and `wicket-examples`, which is teaching material and deliberately not hardened. + +## Why reports are private + +A vulnerability reported in public is known to attackers before a fixed release exists. So a suspected vulnerability goes to [email protected], never into an issue, a pull request, a commit message or a branch name, and stays private until the fix is released and announced. Everything else, such as hardening ideas or a problem in the examples, is welcome in public. When you are not sure which it is, report it privately. diff --git a/_contribute/wicket-test-modules.md b/_contribute/wicket-test-modules.md new file mode 100644 index 00000000..a5fe5870 --- /dev/null +++ b/_contribute/wicket-test-modules.md @@ -0,0 +1,29 @@ +--- +title: Why most tests live in another module +type: explanation +topic: wicket +summary: Why wicket-core's tests are in wicket-core-tests, and why a test run with Maven can use an old build of the code you changed. +order: 60 +--- + +## Tests need WicketTester, and WicketTester needs wicket-core + +Most of Wicket's tests render a page or click a link, and for that they use `WicketTester`. Applications use `WicketTester` too, for their own tests, so it is not test code: it ships as a module of its own, `wicket-tester`. That module depends on `wicket-core`, because it drives Wicket's request cycle. + +A test of `wicket-core` that uses `WicketTester` would make `wicket-core` depend on `wicket-tester`, which already depends on `wicket-core`. Maven does not allow such a cycle. So the tests of `wicket-core` live in a module after both, `wicket-core-tests`, which depends on `wicket-core` and `wicket-tester`. The module is never released; it only holds tests. + +Until Wicket 9, `WicketTester` was part of `wicket-core` itself. It moved out in Wicket 10, and the tests of `wicket-core` moved with it. `wicket-cdi` has a companion `wicket-cdi-tests` as well. Modules that `wicket-tester` does not depend on, such as `wicket-extensions` and `wicket-auth-roles`, can use it in their own tests, and keep those in their own `src/test/java`. So does `wicket-util`, whose tests need nothing of `wicket-core`. + +The tests in `wicket-core-tests` are not only about `wicket-core`. `wicket-request` comes before `wicket-core` in the build, so its own tests cannot use anything from `wicket-core`. A test of a `wicket-request` class that needs a mock request or a page lives in `wicket-core-tests` instead. `UrlRendererTest` is one: it tests `UrlRenderer` from `wicket-request` with the `MockWebRequest` of `wicket-core`. + +## Maven builds only what you ask for + +Maven builds the modules you name, and the modules they need come from somewhere else. With `-pl wicket-core-tests`, Maven builds `wicket-core-tests` only. The `wicket-request`, `wicket-core` and `wicket-tester` it depends on come from your local Maven repository, the jars that the last `mvn install` put there. + +So when you change `wicket-request` and run a test in `wicket-core-tests`, the test runs against the `wicket-request` you installed last, not against the code in your working folder. A test of a bug fix then fails although the fix is right, or passes although the fix is wrong. Maven does not warn about it, because from its point of view nothing is wrong. + +There are two ways around it. Install the changed module before the test run, so that the local repository holds your change. Or add `-am` ("also make"), so that Maven builds the modules the test module depends on from your working folder as well. `-am` builds more, and applies the test selection to every module it builds, so it needs `-Dsurefire.failIfNoSpecifiedTests=false` too. [Build and test Wicket]({{ site.baseurl }}/contribute/wicket-build.html#run-one-test) has the commands. + +## Why the IDE does not have this problem + +IntelliJ IDEA, Eclipse and VS Code read the Maven modules, but compile them themselves. When a module depends on another module of the same project, the IDE uses that module's classes from your working folder instead of the jar in the local repository. A test you run from these IDEs therefore sees your change at once. A full Maven build, `mvn clean verify`, also builds every module from source. Only the run with `-pl` and without `-am` takes the shortcut through the local repository. diff --git a/contribute/index.md b/contribute/index.md index 1577a0aa..e3e395fe 100644 --- a/contribute/index.md +++ b/contribute/index.md @@ -17,7 +17,7 @@ summary: Wicket is built by the people who use it. Help with questions, bugs, th ## Wicket itself {#wicket} -Wicket's code is in [apache/wicket](https://github.com/apache/wicket) on GitHub. Pick an [open issue](https://github.com/apache/wicket/issues), such as one labelled [`good first issue`](https://github.com/apache/wicket/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22), or one you ran into yourself, and send the fix as a pull request against `master`. A committer reviews and merges it and copies a fix to the release lines it applies to. Since Wicket 11 a major relea [...] +Wicket's code is in [apache/wicket](https://github.com/apache/wicket) on GitHub. Pick an [open issue](https://github.com/apache/wicket/issues), such as one labelled [`good first issue`](https://github.com/apache/wicket/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22), or one you ran into yourself, and send the fix as a pull request against `master`. A committer reviews and merges it and copies a fix to the release lines it applies to. Since Wicket 11 a major relea [...] {% include guide-list.html pages=wicket_pages kind=true %}
