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 6962d0ef8baf04109d9af82e6852554b055cdb64 Author: Martijn Dashorst <[email protected]> AuthorDate: Thu Nov 19 15:34:21 2026 +0100 Rewrite the contributor pages for Wicket's code for first-time contributors The pages for contributing to Wicket itself still described the Wicket 6 era: a clone from git-wip-us.apache.org, JDK 6, mvn eclipse:eclipse, -Dmaven.test.skip=true, 6.0-SNAPSHOT, an Eclipse formatter file in wicket-core that is not there, and TravisCI on ARM64. The pull request page listed the end-of-life wicket-9.x and wicket-8.x branches and left out wicket-11.x, and said nothing about the tests living in another module than the code. build.md, ides.md and patch.md become pages of the contribute collection, next to the site-* pages: - Send a pull request to Wicket (how-to): the path from a good first issue to a reviewed pull request against master, in numbered steps. The branch table comes from _data/releases.yml. - Build and test Wicket (how-to): requirements, the fast build, running one test in a -tests module after installing the changed module, the JavaScript tests, the examples with jetty:run, the full build CI runs, and the errors a newcomer meets. - Set up your IDE (how-to): IntelliJ IDEA, Eclipse and NetBeans, with the formatter settings from wicket-eclipse-settings. - Code conventions (reference): format, license header, tests, Javadoc and @since, API changes, pom order, commit messages. The old URLs redirect to the new pages. The commands were run in a fresh clone of apache/wicket master with an empty local Maven repository. Co-Authored-By: Claude Opus 5.5 <[email protected]> --- .htaccess | 3 + _contribute/wicket-build.md | 117 ++++++++++++++++++++++++++++++ _contribute/wicket-conventions.md | 67 +++++++++++++++++ _contribute/wicket-ide.md | 50 +++++++++++++ _contribute/wicket-pull-request.md | 141 +++++++++++++++++++++++++++++++----- contribute/build.md | 145 ------------------------------------- contribute/ides.md | 38 ---------- contribute/index.md | 7 +- contribute/patch.md | 66 ----------------- 9 files changed, 360 insertions(+), 274 deletions(-) diff --git a/.htaccess b/.htaccess index 404a9d2c..63710517 100644 --- a/.htaccess +++ b/.htaccess @@ -14,6 +14,9 @@ RedirectMatch 301 ^/start/wicket-([0-9.]+)\.x\.html$ /versions/wicket-$1.x/ RedirectMatch 301 ^/guide/(.*)$ /docs/$1 Redirect 301 /contribute/write.html /contribute/site-first-change.html Redirect 301 /contribute/userguide.html /contribute/site-docs-page.html +Redirect 301 /contribute/build.html /contribute/wicket-build.html +Redirect 301 /contribute/ides.html /contribute/wicket-ide.html +Redirect 301 /contribute/patch.html /contribute/wicket-pull-request.html # Getting help moved into the community page. RedirectMatch 301 ^/help/?$ /community/ diff --git a/_contribute/wicket-build.md b/_contribute/wicket-build.md new file mode 100644 index 00000000..651f0ec3 --- /dev/null +++ b/_contribute/wicket-build.md @@ -0,0 +1,117 @@ +--- +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 +--- +{% 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. +- **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: + +```shell +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. + +## Build everything + +```shell +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. + +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 [...] + +```shell +mvn install -DskipTests -Pfast -pl wicket-request +mvn verify -pl wicket-core-tests -Dtest=UrlRendererTest +``` + +`-pl` (for "projects") limits the build to the modules you name, with their folder names. Install the changed module again after every change; otherwise the test runs against your previous build. When you changed more than one module, name them all, with quotes: `-pl "wicket-util,wicket-request"`. + +When the test is in the same module as the code, as for most of `wicket-util` and `wicket-extensions`, one command is enough: + +```shell +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. + +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: + +```shell +mvn verify -pl wicket-core-tests -am -Dtest=UrlRendererTest "-Dsurefire.failIfNoSpecifiedTests=false" +``` + +## Run the JavaScript tests {#javascript-tests} + +The JavaScript tests run in a headless Chrome and are off unless you ask for them with `-Pjs-test`: + +```shell +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 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 [...] + +## Run the examples + +The `wicket-examples` module is a web application with an example of almost every component. To see your change in a browser, install the modules you changed and start the examples: + +```shell +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). + +## Run the full build + +Before you send a pull request, build and test everything the way GitHub does: + +```shell +mvn clean verify -Pjs-test +``` + +`clean` removes all earlier build results, `verify` compiles and runs every test, and `-Pjs-test` adds the JavaScript tests. The full build also checks that every file has the ASF license header. It takes much longer than the fast build: on a laptop, count on a quarter of an hour or more. + +While you work, build as little as you need: `-Pfast` and `-DskipTests` to leave things out, `-pl` with the modules you need, and `-o` (offline) so that Maven does not check the internet for newer snapshots. Save the full build for the end. + +## Use your own build in an application + +After `mvn install`, an application on the same computer can use your build. Set the Wicket version in its `pom.xml` to the snapshot version from the root `pom.xml` of your clone: + +```xml +<dependency> + <groupId>org.apache.wicket</groupId> + <artifactId>wicket-core</artifactId> + <version>{% if next %}{{ next.version }}-SNAPSHOT{% else %}<!-- the version in Wicket's root pom.xml -->{% endif %}</version> +</dependency> +``` + +This is a quick way to check a fix in a [quickstart]({{ site.baseurl }}/start/quickstart.html) or in your own application. + +## When the build fails + +- **`release version 21 not supported`**: Maven runs with an older Java. 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. +- **An error about the order of a `pom.xml`**: Wicket's build checks the order of sections and dependencies in every `pom.xml`. See the [conventions]({{ site.baseurl }}/contribute/wicket-conventions.html#poms). diff --git a/_contribute/wicket-conventions.md b/_contribute/wicket-conventions.md new file mode 100644 index 00000000..413a21b4 --- /dev/null +++ b/_contribute/wicket-conventions.md @@ -0,0 +1,67 @@ +--- +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 +--- +{% assign next = site.data.releases.lines | where: "status", "boarding" | 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). + +## 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]({{ 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. + +## 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 {#tests} + +- A test class name ends in `Test`, such as `UrlRendererTest`. Maven runs only classes named `*Test.java`: a class named `UrlRendererTests` or `TestUrlRenderer` compiles but never runs. +- A module with a `-tests` companion keeps its tests there: the tests of `wicket-core` are in `wicket-core-tests`, those of `wicket-cdi` in `wicket-cdi-tests`. Other modules, such as `wicket-util` and `wicket-extensions`, keep their tests in their own `src/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 in `src/test/resources`. +- Tests use JUnit 5. For pages and components, extend `WicketTestCase`, which gives you a `WicketTester` as `tester`. +- JavaScript tests are QUnit tests in `src/test/js/` of `wicket-core` and `wicket-extensions`; see [Run the JavaScript tests]({{ site.baseurl }}/contribute/wicket-build.html#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 `@since` tag with the first release it appears in: {% if next %}`@since {{ next.version }}` on `master`{% else %}the version of `master` without `-SNAPSHOT`{% endif %}. +- 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. 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. + +## poms {#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, 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). | + +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. diff --git a/_contribute/wicket-ide.md b/_contribute/wicket-ide.md new file mode 100644 index 00000000..06247790 --- /dev/null +++ b/_contribute/wicket-ide.md @@ -0,0 +1,50 @@ +--- +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 +--- + +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. + +## 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. + +## 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. + +To format only your changes, use **Code → Reformat Code** with **Only changes uncommitted to VCS**. + +### Run a test + +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. + +### Run the examples {#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>, 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**. + +## Eclipse + +Use the Eclipse IDE for Java Developers or for Enterprise Java, which include Maven support. + +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**. + +To format only your changes, set **Window → Preferences → Java → Editor → Save Actions** to format edited lines. + +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. + +## 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. diff --git a/_contribute/wicket-pull-request.md b/_contribute/wicket-pull-request.md index 0fd1eb16..5a9a4a1f 100644 --- a/_contribute/wicket-pull-request.md +++ b/_contribute/wicket-pull-request.md @@ -2,15 +2,26 @@ title: Send a pull request to Wicket type: howto topic: wicket -summary: Fork apache/wicket, pick the branch of the line you change, and send your fix or feature as a pull request. +summary: From an issue to a reviewed pull request against apache/wicket, for your first contribution or your fiftieth. order: 10 --- +{% 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. + +## 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. -Wicket's code lives in [apache/wicket](https://github.com/apache/wicket) on GitHub. Changes arrive as pull requests, and a committer reviews and merges them. For a bug, first [open an issue](https://github.com/apache/wicket/issues) that describes it, ideally with a [quickstart]({{ site.baseurl }}/start/quickstart.html) that shows it, and refer to the issue from your pull request. +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. -## Fork and clone +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). -Fork apache/wicket on GitHub, clone your fork, and add the Wicket repository as `upstream`: +## 2. Fork and clone + +Fork apache/wicket on GitHub with the Fork button. Clone your fork and add the Wicket repository as `upstream`: ```shell git clone https://github.com/<your-account>/wicket.git @@ -18,34 +29,124 @@ cd wicket git remote add upstream https://github.com/apache/wicket.git ``` -## Pick the branch +## 3. Create a branch from master -Every release line has a branch. Start from the branch of the line your change is for: -{% assign next = site.data.releases.lines | where: "status", "boarding" | first %} +Wicket has a branch for every release line, a major version that still gets releases: + +| Branch | Release line | Pull requests | +|---|---|---| +| `master` | {% if next %}Wicket {{ next.series }}, not released yet ({{ next.when }}){% else %}The next major release{% endif %} | Send them here. | +{% if current %}| `wicket-{{ current.series }}.x` | Wicket {{ current.series }}, the current release | Committers copy fixes here. | +{% endif %}{% if lts %}| `wicket-{{ lts.series }}.x` | Wicket {{ lts.series }}, long-term support (LTS) | Committers copy fixes here. | +{% endif %} -| Branch | Line | -|---|---| -| `master` | The next major release{% if next %}, Wicket {{ next.series }}{% endif %}. New features go here. | -| `wicket-10.x` | Wicket 10, the LTS. Fixes that the LTS needs. | -| `wicket-9.x`, `wicket-8.x` | Wicket 9 and 8, until their end of life. | +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/`. -When a fix is needed on more than one line, say which lines the bug affects in the pull request; the committers decide where it is merged and backported. +Give your branch a name that says what it does: ```shell git fetch upstream -git checkout -b fix-dropdown-null upstream/master +git checkout -b keep-url-fragment upstream/master +``` + +## 4. Build Wicket + +Build everything once, without the tests. The first time, this downloads the libraries Wicket uses and takes a few minutes: + +```shell +mvn install -DskipTests -Pfast +``` + +It ends with `BUILD SUCCESS`. [Build and test Wicket]({{ site.baseurl }}/contribute/wicket-build.html) explains the options and what to do when the build fails. To work in IntelliJ IDEA, Eclipse or NetBeans, see [Set up your IDE]({{ site.baseurl }}/contribute/wicket-ide.html). + +## 5. Change the code and add a test {#change} + +Make the change, and add a test that fails without it and passes with it. A bug fix without a test is rarely merged. + +The test is often in a different module than the code. The tests for `wicket-core`, for example, are in `wicket-core-tests`. Find the existing test of a class by its name plus `Test`: + +```shell +git ls-files "*/UrlRendererTest.java" +``` + +Run the test with Maven. Because the test is in another module, Maven uses the module you changed from your local Maven repository, so install the changed module first: + +```shell +mvn install -DskipTests -Pfast -pl wicket-request +mvn verify -pl wicket-core-tests -Dtest=UrlRendererTest +``` + +Repeat both commands after every change. Without the first one, the test runs against your previous build and passes or fails for the wrong reason. [Run one test]({{ site.baseurl }}/contribute/wicket-build.html#run-one-test) has the details, and [Run the JavaScript tests]({{ site.baseurl }}/contribute/wicket-build.html#javascript-tests) covers changes to `.js` files. + +Follow the [code conventions]({{ site.baseurl }}/contribute/wicket-conventions.html): the code format of the file you edit, the license header on every new file, `@since` on new public methods and classes, and a test class name that ends in `Test`. + +## 6. Run the full build + +Before you send the pull request, build and test everything the way GitHub does it for every pull request: + +```shell +mvn clean verify -Pjs-test +``` + +This runs all tests, the JavaScript tests and the license header check, and takes longer: on a laptop, count on a quarter of an hour or more. It has to end with `BUILD SUCCESS`. + +## 7. Commit + +Commit your change with a message in this form: + +```text +Keep the fragment in UrlRenderer.renderFullUrl + +renderRelativeUrl kept the fragment of a URL, but renderFullUrl dropped +it, so a full URL to a page section pointed to the top of the page. +renderFullUrl now appends the fragment in the same way. + +GitHub issue #<number> ``` -## Build and test +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). -Build Wicket with Maven and run the tests before you send the change: +Check which files you changed, add them, and commit: ```shell -mvn clean install +git status +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 commit` opens a text editor for the message. If it opens one you do not know, set your own with `git config --global core.editor`, or commit from the commit window of your IDE. + +## 8. Open the pull request {#github} + +Push the branch to your fork: + +```shell +git push -u origin keep-url-fragment +``` + +GitHub does not accept your password here. Sign in with the [GitHub CLI or a personal access token](https://docs.github.com/en/get-started/git-basics/caching-your-github-credentials-in-git), or clone over SSH. + +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. + +## 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: + +```shell +git fetch upstream +git merge upstream/master +git push ``` -[Build from source]({{ site.baseurl }}/contribute/build.html) covers the build in more detail, and [Set up your IDE]({{ site.baseurl }}/contribute/ides.html) the code style. +A committer merges the pull request when it is ready. The change goes out with the next {% if next %}Wicket {{ next.series }}{% else %}major{% endif %} release, and with the next release of every older line it was copied to. -## Send the pull request +## Ask questions {#questions} -Push your branch to your fork and open a pull request against the branch you started from. Describe what changes and why, and link the issue. The project discusses larger changes on the [developers list]({{ site.baseurl }}/community/#dev); a short mail there with a link to your pull request helps it get noticed. +Ask in the issue you work on, in [GitHub Discussions](https://github.com/apache/wicket/discussions), or on the developers list, [[email protected]](mailto:[email protected]). Questions about building Wicket, finding code or writing a test are normal there. To write to the list, subscribe first by sending a mail to [[email protected]](mailto:[email protected]); the [archive](https://lists.apache.org/[email protected]) shows earlier conversations. diff --git a/contribute/build.md b/contribute/build.md deleted file mode 100644 index 66092949..00000000 --- a/contribute/build.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -layout: default -title: Build from source ---- - -The Wicket projects are built using a multi-module build as proposed by the -Maven project. We use Maven to build our projects and distributions. To be -able to build Wicket directly from subversion, you will need an understanding -of Maven. - -This document contains the following sections. - -1. Getting your Wicket version -2. Building Wicket -3. Coping with test failures -4. Using your own built artifacts - -For more information on the project structure, please read the 'Better Builds -With Maven' book which has a detailed description on how to structure a -maintainable, enterprise ready build. The book is available for free from the -Mergere website. - -## Getting your Wicket version ## - -Clone the master branch from Apache Git Wicket repository - -{% highlight console %} -$ git clone http://git-wip-us.apache.org/repos/asf/wicket.git -{% endhighlight %} - -This will give you a directory structure like the following directory tree: - -{% highlight console %} -wicket -wicket/wicket-core -wicket/wicket-extensions -wicket/wicket-spring -wicket/wicket-auth-roles -wicket/wicket-examples -wicket/wicket-spring-annot -... -{% endhighlight %} - -To check out a different branch use: -{% highlight console %} -$ cd wicket -$ git checkout -b release/wicket-x.y.z release/wicket-x.y.z -# verify the branch with: -$ git branch -{% endhighlight %} - -In this document we focus at the maven project descriptor located in the top -level directory, which enforces default settings for all Wicket projects such -as plug-in settings, versioning of the Wicket projects, managing the various -dependencies and more. - -The artifacts in this project are there only for having a consistent build. -This top-level project doesn't have sources for itself. - -## Building Wicket ## - -The current development version of Wicket requires at least jdk 6. - -If you want to ensure that your Wicket version is built using JDK-6 and -fully compatible with that Java version, you will need to build it with a Java -6 compiler and runtime library. - -If you haven't done so already change into the Wicket root directory: - -{% highlight console %} -cd wicket -{% endhighlight %} - -Now building all of Wicket is as simple as issuing the following command: - -{% highlight console %} -mvn install -{% endhighlight %} - -This will compile, test, package and install all Wicket projects. Installation -means putting the jar files into your local Maven repository, including the -source, but without the javadoc jars (this is a Wicket specific configuration, -because build javadoc takes a long time). - -The following commands are useful: -<table> -<tr><th>Commandline</th><th>Description</th></tr> -<tr><td>`mvn clean`</td><td>cleans up build artifacts</td></tr> -<tr><td>`mvn compile`</td><td>compiles the projects</td></tr> -<tr><td>`mvn package`</td><td>creates the jar files in the target/ subdirectories</td></tr> -<tr><td>`mvn install`</td><td>installs the jar files in your local repository</td></tr> -<tr><td>`mvn -Prelease package`</td><td>generates the javadoc/source jars as well</td></tr> -</table> - -You can just run the install target, as Maven will build the previous stages -automatically. - -### Coping with test failures ### - -As this is our main development you might/will encounter failing unit tests. -These can be skipped using: - -{% highlight console %} -mvn -Dmaven.test.skip=true install -{% endhighlight %} - -Of course, all bets are off then and your mileage may vary if you use such a -built jar. - -### Using your own built artifacts ### - -Now you have built your own fresh Wicket jar you must be anxious to use it. -This is now as simple as adding a snapshot dependency on the specific Wicket -version. So in your pom.xml you can use: - -{% highlight xml %} -<dependency> - <groupId>org.apache.wicket</groupId> - <artifactId>wicket-core</artifactId> - <version>6.0-SNAPSHOT</version> - <scope>compile</scope> -</dependency> -{% endhighlight %} - -And adding this to your Eclipse, NetBeans or IntelliJ IDEA project classpath -is then as simple as: - -{% highlight console %} -mvn eclipse:eclipse -{% endhighlight %} - -or opening the project using Netbeans or IDEAs Maven integration. - -Maven will then add all the necessary JAR files to the project's classpath. - -One thing you need to make sure is that you have set the `M2_REPO` classpath -variable in Eclipse (or a similar construct in Netbeans), and point it to your -local repository, typically found in `C:\Documents and Settings\username\.m2\repo` -or (for unix buffs) `~/.m2/repo` - -You can add this setting using maven: - -{% highlight console %} -mvn -Declipse.workspace=<path-to-eclipse-workspace> eclipse:add-maven-repo -{% endhighlight %} diff --git a/contribute/ides.md b/contribute/ides.md deleted file mode 100644 index 013f7126..00000000 --- a/contribute/ides.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: default -title: IDE Support for Wicket development ---- - -For Wicket plugins that help you build applications, see [Add Wicket support to your IDE]({{ site.baseurl }}/docs/ide-plugins.html) in the user guide. This page covers setting up your IDE to work on Wicket itself. - -## Setting up your IDE ## - -### Eclipse ### - -Eclipse offers a native for Maven based projects. To import a maven project just go to 'File...->Import...->Existing Maven Projects' and import one or more Maven projects into your workspace. - -Alternatively, you can generate an Eclipse project typing the following command on project's root: - -{% highlight console %} -mvn eclipse:eclipse -{% endhighlight %} - -Maven will add all the necessary JAR files to the project's classpath. Now the sources can be imported in Eclipse using the "Existing Projects into Workspace" wizard. - -If you want to go along with the Wicket way of code formatting you should import the Wicket code format profile into your workspace (Preferences->Java->Code Style->Formatter), found in: - -{% highlight console %} -<path-to-eclipse-workspace>/wicket-core/EclipseCodeFormat.xml -{% endhighlight %} - -Finally configure the editor to automatically format all edited lines and organize imports on save (Preferences->Java->Editor->Save Actions). - -### NetBeans ### - -NetBeans comes with Maven integration. Further help can be found at their [Wiki](http://wiki.netbeans.org/MavenBestPractices "NetBeans Community Wiki") - -### IDEA ### - -IntelliJ IDEA comes with [Maven support](http://www.jetbrains.com/idea/webhelp/maven.html "IDEA Web Help") too. - -With the [Eclipse Code Formatter plugin](http://plugins.jetbrains.com/plugin/6546) the Wicket format profile can be used in IntelliJ IDEA too. Configure the IDE to prevent star imports (Settings->Code Style->Imports). diff --git a/contribute/index.md b/contribute/index.md index d877375c..1577a0aa 100644 --- a/contribute/index.md +++ b/contribute/index.md @@ -17,14 +17,11 @@ 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) or one you ran into yourself, and send the fix as a pull request: a committer reviews and merges it, and it goes out with the next release of its line. Since Wicket 11 a major release ships [every three months]({{ site.baseurl }}/versions/#release-policy), so a change merged today reaches users within a quarter. New features go to `master`, the ne [...] +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 %} -- [Build from source]({{ site.baseurl }}/contribute/build.html): check out a branch, build it with Maven and use your own build. -- [Set up your IDE]({{ site.baseurl }}/contribute/ides.html): import the projects into Eclipse, IntelliJ IDEA or NetBeans, with the code format. -- [Fix a bug or add a feature]({{ site.baseurl }}/contribute/patch.html): from an issue to a pull request. -- For committers, [Build a release]({{ site.baseurl }}/contribute/release.html) still describes the release process of Wicket 6 and older and needs an update. +For committers, [Build a release]({{ site.baseurl }}/contribute/release.html) still describes the release process of Wicket 6 and older and needs an update. ## Without writing code {#without-code} diff --git a/contribute/patch.md b/contribute/patch.md deleted file mode 100644 index 9d75fda9..00000000 --- a/contribute/patch.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -layout: default -title: Improve Wicket with fixes and new features! ---- - -# So you have found a bug... {#reportbug} - -As developers we all strive to produce a flawless software. However, in -the real world we might find that our code contains errors or bugs. -Wicket tracks bugs and new features in [GitHub -Issues](https://github.com/apache/wicket/issues). If you think you have -found a bug follow these simple steps before opening a new issue: - -* Test the very last version of Wicket to see if the bug was already - fixed - -* Search [our issues](https://github.com/apache/wicket/issues?q=is%3Aissue) - and the mailing list to see if it's already been discussed. Issues - reported before 2026 live in our read-only [JIRA - archive](https://issues.apache.org/jira/browse/WICKET), which is worth - searching too. - -* Simply ask to the [devs](mailto:[email protected]) mailing list - if you are unsure. - -## Create an issue ## - -Either you have spotted a bug or you want to propose a new feature, the -first thing to do is to create an issue with the following steps: - -* Create a new [issue](https://github.com/apache/wicket/issues/new). The - issue might already exist if you have found a regression. - -* Write a short description of the issue. If this one is a bug, report - the affected version as well. - -* [Create a quickstart](../start/quickstart.html) that you can use for - prototyping the feature or demonstrating the bug. - -## Time for some coding ## - -Wicket uses [Git](http://git-scm.com/) as versioning system, so you -need to have it properly installed and configured to start work on -Wicket code base. The repository lives on -[GitHub](https://github.com/apache/wicket), and contributions reach us -as pull requests against it. - -**NOTE:** when you are working on Wicket code, please follow our code -format rules. You can find them inside wicket-core module as Eclipse code formatter profile. - -**NOTE:** when you are using Eclipse IDE, please ensure that you have -installed "M2E Settings" from the Eclipse Marketplace in addition to -the format rules. - -### Create a pull request {#github} - -To create a pull request on GitHub follow the instructions you can find -[here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). -Mention the issue your work addresses in the description, so that the -pull request and the issue link up. Once you have finished to work on -your pull request, send us an email using the -[devs](mailto:[email protected]) mailing list. - -All Pull Requests are automatically tested at -[Github Actions](https://github.com/apache/wicket/actions) on AMD64 and -at [TravisCI](https://travis-ci.com/github/apache/wicket/) on ARM64 platform.
