dashorst commented on code in PR #1869:
URL: https://github.com/apache/wicket/pull/1869#discussion_r4508001362


##########
AGENTS.md:
##########
@@ -33,6 +33,9 @@ header — copy it when you add one.
 - Prepare the change and stop. Whether it goes in as a direct push to master 
or as a pull request
   is the committer's call, and the push itself is never yours: don't push, 
don't open a pull
   request, don't tag unless you were told to do so.
+- Before you hand a change over, check it against `REVIEW.md`: it lists what a 
review looks for
+  beyond these conventions — licensing, OSGi and JPMS, performance, 
serialization, accessibility,
+  documentation and tests.

Review Comment:
   This pointer fires only when a change is handed over. An agent asked to 
review a pull request has nothing that sends it to `REVIEW.md`. Covering both 
cases, and dropping "beyond these conventions", which REVIEW.md already says 
itself:
   
   ```suggestion
   - Before handing a change over, and when reviewing a pull request, apply 
every section of
     `REVIEW.md` the change triggers: licensing, OSGi and JPMS, performance, 
serialization,
     accessibility, documentation and tests.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,118 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+# Reviewing a change to Apache Wicket
+
+What a review of a pull request checks, whoever does it: a committer, a 
contributor or an agent.
+The conventions for writing a change — format, commits, build, API 
compatibility, Javadoc,
+comments, language and security — are in `AGENTS.md`. A review checks the 
change against those as
+well; this file adds what is easy to miss when a change otherwise looks right.
+
+Most changes touch only a few of the sections below. A section that doesn't 
apply needs no
+comment, but one that does apply needs an answer in the change itself, not a 
promise to follow
+up.

Review Comment:
   "Applies" has no observable bound. The agent decides it, and the cheap way 
out is to call a section not applicable. I suggest opening each section with a 
checkable trigger instead of its rationale paragraph, for example:
   
   - OSGi and JPMS: "Applies when the change adds, moves, renames or removes a 
package, adds a dependency, or touches `module-info.java` or an `osgi.*` 
property."
   - Serialization: "Applies when a component, behavior or model gains or 
changes a field, or stores a lambda or anonymous class."
   - Performance: fold the hot-path list from line 65 into the trigger.
   
   The rationale can stay as a clause after the trigger. This paragraph then 
becomes the completion criterion for both the self-check and a review, and it 
also says what a review produces:
   
   ```suggestion
   Each section opens with when it applies. A review is done when every section 
the change
   triggers is accounted for: confirmed, or a finding naming the file and line. 
A finding is
   resolved in the change itself, in the same pull request.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,118 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+# Reviewing a change to Apache Wicket
+
+What a review of a pull request checks, whoever does it: a committer, a 
contributor or an agent.
+The conventions for writing a change — format, commits, build, API 
compatibility, Javadoc,
+comments, language and security — are in `AGENTS.md`. A review checks the 
change against those as
+well; this file adds what is easy to miss when a change otherwise looks right.
+
+Most changes touch only a few of the sections below. A section that doesn't 
apply needs no
+comment, but one that does apply needs an answer in the change itself, not a 
promise to follow
+up.
+
+## License compliance
+
+- Every new file carries the ASF license header. Apache RAT checks this during 
the build, so a
+  missing header fails it; files that can't carry one belong in 
`.rat-excludes`, with a reason.
+- A new dependency, or a new version of one, is under a license the ASF 
allows: category A, or
+  category B, which may only be included in binary form, never as source 
copied into the tree.
+  Category X licenses (GPL, AGPL, LGPL and their like) are never allowed. The 
categories are
+  listed at https://www.apache.org/legal/resolved.html.
+- Third-party code, scripts, styles, fonts or images copied into the source 
tree are listed in
+  `LICENSE`, with the license text in `licenses/`. When they end up in a 
published jar, they are
+  listed in `LICENSE-binary` as well. `NOTICE` changes only when the third 
party's own license or
+  NOTICE file requires an attribution there.
+- A Maven dependency is not bundled, so it needs no entry in these files, 
unless it is shaded or
+  copied into a Wicket artifact.
+
+## OSGi and JPMS
+
+Every published module is both an OSGi bundle, built by `maven-bundle-plugin` 
from the
+`osgi.export.package` and `osgi.import.package` properties in its pom, and a 
JPMS module, described
+by its `module-info.java`.
+
+- A package that is added, moved, renamed or removed is exported or dropped in 
both places.
+  `wicket-core` and `wicket-extensions` list their exported packages one by 
one, so a new package
+  there isn't exported until it is added to the list; the other modules export 
by wildcard.
+- A new dependency is a `requires` in `module-info.java`. An optional one is
+  `<optional>true</optional>` in the pom and `requires static` in 
`module-info.java`; the bundle
+  plugin then imports its packages with `resolution:=optional`. Check the 
`Import-Package`
+  header of the built jar's manifest when in doubt.
+- The import version ranges stay usable: a range that excludes a version 
applications commonly
+  run breaks them in an OSGi container even when the build passes.
+
+## Performance
+
+Wicket renders every page by walking its component tree, and stores pages in 
the session and the
+page store, so small costs in core classes multiply.
+
+- A change to a hot path keeps its time complexity and its memory footprint 
per component. Hot
+  paths include `Component` and `ComponentState`, `MarkupContainer` children, 
rendering,
+  markup parsing and loading, request mapping and handling, models, and page 
serialization.
+- A change that makes such a path slower or larger says so in the commit 
message and justifies it,
+  with numbers from `wicket-benchmarks` where it can be measured.
+- A replacement for a library class — a collection, a cache, a parser — keeps 
the complexity of
+  every operation Wicket relies on, not only the common ones. Removing a 
dependency is no reason to
+  give up a performance gain.
+
+## Serialization
+
+Pages are serialized into the page store, and with them every component, 
behavior and model they
+hold.
+
+- A field added to a component, behavior or model adds to the size of every 
stored page that
+  holds one. A field that can be computed or loaded again belongs in a 
transient field or a
+  detachable model.
+- A change to the serialized form — a new field type, a different collection 
class, a changed
+  `serialVersionUID` — means pages stored by the previous version can't be 
read back. That is
+  acceptable in a major release on `master`, never on a maintenance line, and 
is described in
+  the migration guide.
+- A lambda or anonymous class stored in a component has to be serializable; 
Wicket's lambda-based
+  API takes the `Serializable*` interfaces for that reason.
+
+## Accessibility
+
+Components, their markup and the JavaScript that comes with them produce the 
HTML of every
+application that uses them, so their accessibility is the applications' 
accessibility.
+
+- Markup, components and JavaScript that render UI meet WCAG 2.2 at level AA, 
or at least don't
+  make an existing component less accessible than it was.
+- Check in particular: form controls have labels, images have text 
alternatives, roles and ARIA
+  attributes are correct and kept in sync with the state they describe, 
everything that works with
+  a mouse works with a keyboard, focus is not lost or moved unexpectedly by an 
Ajax update, and
+  changes announced only visually are also announced to assistive technology 
where that matters.
+- An example or a test page is not exempt: the examples are what applications 
copy.

Review Comment:
   Stated positively, so the exemption isn't what gets primed:
   
   ```suggestion
   - Examples and test pages meet the same bar: they are what applications copy.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,118 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+# Reviewing a change to Apache Wicket
+
+What a review of a pull request checks, whoever does it: a committer, a 
contributor or an agent.
+The conventions for writing a change — format, commits, build, API 
compatibility, Javadoc,
+comments, language and security — are in `AGENTS.md`. A review checks the 
change against those as
+well; this file adds what is easy to miss when a change otherwise looks right.
+
+Most changes touch only a few of the sections below. A section that doesn't 
apply needs no
+comment, but one that does apply needs an answer in the change itself, not a 
promise to follow
+up.
+
+## License compliance
+
+- Every new file carries the ASF license header. Apache RAT checks this during 
the build, so a
+  missing header fails it; files that can't carry one belong in 
`.rat-excludes`, with a reason.

Review Comment:
   AGENTS.md already requires the header, and RAT enforces it. The 
`.rat-excludes` part is the only thing here an agent can't find out by looking.
   
   ```suggestion
   - A file that can't carry the ASF license header is listed in 
`.rat-excludes`, with a reason;
     RAT fails the build on any other file without one.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,118 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+# Reviewing a change to Apache Wicket
+
+What a review of a pull request checks, whoever does it: a committer, a 
contributor or an agent.
+The conventions for writing a change — format, commits, build, API 
compatibility, Javadoc,
+comments, language and security — are in `AGENTS.md`. A review checks the 
change against those as
+well; this file adds what is easy to miss when a change otherwise looks right.
+
+Most changes touch only a few of the sections below. A section that doesn't 
apply needs no
+comment, but one that does apply needs an answer in the change itself, not a 
promise to follow
+up.
+
+## License compliance
+
+- Every new file carries the ASF license header. Apache RAT checks this during 
the build, so a
+  missing header fails it; files that can't carry one belong in 
`.rat-excludes`, with a reason.
+- A new dependency, or a new version of one, is under a license the ASF 
allows: category A, or
+  category B, which may only be included in binary form, never as source 
copied into the tree.
+  Category X licenses (GPL, AGPL, LGPL and their like) are never allowed. The 
categories are
+  listed at https://www.apache.org/legal/resolved.html.
+- Third-party code, scripts, styles, fonts or images copied into the source 
tree are listed in
+  `LICENSE`, with the license text in `licenses/`. When they end up in a 
published jar, they are
+  listed in `LICENSE-binary` as well. `NOTICE` changes only when the third 
party's own license or
+  NOTICE file requires an attribution there.
+- A Maven dependency is not bundled, so it needs no entry in these files, 
unless it is shaded or
+  copied into a Wicket artifact.
+
+## OSGi and JPMS
+
+Every published module is both an OSGi bundle, built by `maven-bundle-plugin` 
from the
+`osgi.export.package` and `osgi.import.package` properties in its pom, and a 
JPMS module, described
+by its `module-info.java`.
+
+- A package that is added, moved, renamed or removed is exported or dropped in 
both places.
+  `wicket-core` and `wicket-extensions` list their exported packages one by 
one, so a new package
+  there isn't exported until it is added to the list; the other modules export 
by wildcard.
+- A new dependency is a `requires` in `module-info.java`. An optional one is
+  `<optional>true</optional>` in the pom and `requires static` in 
`module-info.java`; the bundle
+  plugin then imports its packages with `resolution:=optional`. Check the 
`Import-Package`
+  header of the built jar's manifest when in doubt.
+- The import version ranges stay usable: a range that excludes a version 
applications commonly
+  run breaks them in an OSGi container even when the build passes.
+
+## Performance
+
+Wicket renders every page by walking its component tree, and stores pages in 
the session and the
+page store, so small costs in core classes multiply.
+
+- A change to a hot path keeps its time complexity and its memory footprint 
per component. Hot
+  paths include `Component` and `ComponentState`, `MarkupContainer` children, 
rendering,
+  markup parsing and loading, request mapping and handling, models, and page 
serialization.
+- A change that makes such a path slower or larger says so in the commit 
message and justifies it,
+  with numbers from `wicket-benchmarks` where it can be measured.
+- A replacement for a library class — a collection, a cache, a parser — keeps 
the complexity of
+  every operation Wicket relies on, not only the common ones. Removing a 
dependency is no reason to
+  give up a performance gain.

Review Comment:
   The last sentence is a rule shaped by one incident (the first draft of 
#1865), and "every operation Wicket relies on" already covers it.
   
   ```suggestion
   - A replacement for a library class — a collection, a cache, a parser — 
keeps the complexity of
     every operation Wicket relies on, not only the common ones.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,118 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+# Reviewing a change to Apache Wicket
+
+What a review of a pull request checks, whoever does it: a committer, a 
contributor or an agent.
+The conventions for writing a change — format, commits, build, API 
compatibility, Javadoc,
+comments, language and security — are in `AGENTS.md`. A review checks the 
change against those as
+well; this file adds what is easy to miss when a change otherwise looks right.
+
+Most changes touch only a few of the sections below. A section that doesn't 
apply needs no
+comment, but one that does apply needs an answer in the change itself, not a 
promise to follow
+up.
+
+## License compliance
+
+- Every new file carries the ASF license header. Apache RAT checks this during 
the build, so a
+  missing header fails it; files that can't carry one belong in 
`.rat-excludes`, with a reason.
+- A new dependency, or a new version of one, is under a license the ASF 
allows: category A, or
+  category B, which may only be included in binary form, never as source 
copied into the tree.
+  Category X licenses (GPL, AGPL, LGPL and their like) are never allowed. The 
categories are
+  listed at https://www.apache.org/legal/resolved.html.
+- Third-party code, scripts, styles, fonts or images copied into the source 
tree are listed in
+  `LICENSE`, with the license text in `licenses/`. When they end up in a 
published jar, they are
+  listed in `LICENSE-binary` as well. `NOTICE` changes only when the third 
party's own license or
+  NOTICE file requires an attribution there.
+- A Maven dependency is not bundled, so it needs no entry in these files, 
unless it is shaded or
+  copied into a Wicket artifact.
+
+## OSGi and JPMS
+
+Every published module is both an OSGi bundle, built by `maven-bundle-plugin` 
from the
+`osgi.export.package` and `osgi.import.package` properties in its pom, and a 
JPMS module, described
+by its `module-info.java`.
+
+- A package that is added, moved, renamed or removed is exported or dropped in 
both places.
+  `wicket-core` and `wicket-extensions` list their exported packages one by 
one, so a new package
+  there isn't exported until it is added to the list; the other modules export 
by wildcard.
+- A new dependency is a `requires` in `module-info.java`. An optional one is
+  `<optional>true</optional>` in the pom and `requires static` in 
`module-info.java`; the bundle
+  plugin then imports its packages with `resolution:=optional`. Check the 
`Import-Package`
+  header of the built jar's manifest when in doubt.
+- The import version ranges stay usable: a range that excludes a version 
applications commonly
+  run breaks them in an OSGi container even when the build passes.
+
+## Performance
+
+Wicket renders every page by walking its component tree, and stores pages in 
the session and the
+page store, so small costs in core classes multiply.
+
+- A change to a hot path keeps its time complexity and its memory footprint 
per component. Hot
+  paths include `Component` and `ComponentState`, `MarkupContainer` children, 
rendering,
+  markup parsing and loading, request mapping and handling, models, and page 
serialization.
+- A change that makes such a path slower or larger says so in the commit 
message and justifies it,
+  with numbers from `wicket-benchmarks` where it can be measured.
+- A replacement for a library class — a collection, a cache, a parser — keeps 
the complexity of
+  every operation Wicket relies on, not only the common ones. Removing a 
dependency is no reason to
+  give up a performance gain.
+
+## Serialization
+
+Pages are serialized into the page store, and with them every component, 
behavior and model they
+hold.
+
+- A field added to a component, behavior or model adds to the size of every 
stored page that
+  holds one. A field that can be computed or loaded again belongs in a 
transient field or a
+  detachable model.
+- A change to the serialized form — a new field type, a different collection 
class, a changed
+  `serialVersionUID` — means pages stored by the previous version can't be 
read back. That is
+  acceptable in a major release on `master`, never on a maintenance line, and 
is described in
+  the migration guide.
+- A lambda or anonymous class stored in a component has to be serializable; 
Wicket's lambda-based
+  API takes the `Serializable*` interfaces for that reason.
+
+## Accessibility
+
+Components, their markup and the JavaScript that comes with them produce the 
HTML of every
+application that uses them, so their accessibility is the applications' 
accessibility.
+
+- Markup, components and JavaScript that render UI meet WCAG 2.2 at level AA, 
or at least don't
+  make an existing component less accessible than it was.
+- Check in particular: form controls have labels, images have text 
alternatives, roles and ARIA
+  attributes are correct and kept in sync with the state they describe, 
everything that works with
+  a mouse works with a keyboard, focus is not lost or moved unexpectedly by an 
Ajax update, and
+  changes announced only visually are also announced to assistive technology 
where that matters.
+- An example or a test page is not exempt: the examples are what applications 
copy.
+
+## Documentation
+
+- A change users notice — a new feature, a changed default, a removed or 
renamed API, a change in
+  behavior or in dependencies — updates the documentation in the same pull 
request: the Javadoc,
+  the user guide in `wicket-user-guide`, and for anything that breaks or 
changes an existing
+  application, `migration-to-<major>.md` in the root of the branch.
+- A mechanical API change comes with an OpenRewrite recipe in 
`wicket-migration`, as `AGENTS.md`
+  describes.

Review Comment:
   This line is right about where the migration guide lives, but 
AGENTS.md:104-107 still says it is on the wiki and only a human can write it. 
The guides are in the branches now: `migration-to-12.md` on master, 
`migration-to-11.md` on wicket-11.x, `migration-to-10.md` on wicket-10.x. I 
suggest fixing AGENTS.md in this PR so it defines the migration path once (an 
entry in `migration-to-<major>.md` in the root of the branch, plus an 
OpenRewrite recipe where the change is mechanical), with this section pointing 
to it:
   
   ```suggestion
   - A change users notice — a new feature, a changed default, a removed or 
renamed API, a change in
     behavior or in dependencies — updates the Javadoc and the user guide in 
`wicket-user-guide`.
   - A change that breaks or changes an existing application comes with its 
migration path, as
     `AGENTS.md` describes.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,118 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+# Reviewing a change to Apache Wicket
+
+What a review of a pull request checks, whoever does it: a committer, a 
contributor or an agent.
+The conventions for writing a change — format, commits, build, API 
compatibility, Javadoc,
+comments, language and security — are in `AGENTS.md`. A review checks the 
change against those as
+well; this file adds what is easy to miss when a change otherwise looks right.
+
+Most changes touch only a few of the sections below. A section that doesn't 
apply needs no
+comment, but one that does apply needs an answer in the change itself, not a 
promise to follow
+up.
+
+## License compliance
+
+- Every new file carries the ASF license header. Apache RAT checks this during 
the build, so a
+  missing header fails it; files that can't carry one belong in 
`.rat-excludes`, with a reason.
+- A new dependency, or a new version of one, is under a license the ASF 
allows: category A, or
+  category B, which may only be included in binary form, never as source 
copied into the tree.
+  Category X licenses (GPL, AGPL, LGPL and their like) are never allowed. The 
categories are
+  listed at https://www.apache.org/legal/resolved.html.
+- Third-party code, scripts, styles, fonts or images copied into the source 
tree are listed in
+  `LICENSE`, with the license text in `licenses/`. When they end up in a 
published jar, they are
+  listed in `LICENSE-binary` as well. `NOTICE` changes only when the third 
party's own license or
+  NOTICE file requires an attribution there.
+- A Maven dependency is not bundled, so it needs no entry in these files, 
unless it is shaded or
+  copied into a Wicket artifact.
+
+## OSGi and JPMS
+
+Every published module is both an OSGi bundle, built by `maven-bundle-plugin` 
from the
+`osgi.export.package` and `osgi.import.package` properties in its pom, and a 
JPMS module, described
+by its `module-info.java`.
+
+- A package that is added, moved, renamed or removed is exported or dropped in 
both places.
+  `wicket-core` and `wicket-extensions` list their exported packages one by 
one, so a new package
+  there isn't exported until it is added to the list; the other modules export 
by wildcard.
+- A new dependency is a `requires` in `module-info.java`. An optional one is
+  `<optional>true</optional>` in the pom and `requires static` in 
`module-info.java`; the bundle
+  plugin then imports its packages with `resolution:=optional`. Check the 
`Import-Package`
+  header of the built jar's manifest when in doubt.
+- The import version ranges stay usable: a range that excludes a version 
applications commonly
+  run breaks them in an OSGi container even when the build passes.
+
+## Performance
+
+Wicket renders every page by walking its component tree, and stores pages in 
the session and the
+page store, so small costs in core classes multiply.
+
+- A change to a hot path keeps its time complexity and its memory footprint 
per component. Hot
+  paths include `Component` and `ComponentState`, `MarkupContainer` children, 
rendering,
+  markup parsing and loading, request mapping and handling, models, and page 
serialization.
+- A change that makes such a path slower or larger says so in the commit 
message and justifies it,
+  with numbers from `wicket-benchmarks` where it can be measured.
+- A replacement for a library class — a collection, a cache, a parser — keeps 
the complexity of
+  every operation Wicket relies on, not only the common ones. Removing a 
dependency is no reason to
+  give up a performance gain.
+
+## Serialization
+
+Pages are serialized into the page store, and with them every component, 
behavior and model they
+hold.
+
+- A field added to a component, behavior or model adds to the size of every 
stored page that
+  holds one. A field that can be computed or loaded again belongs in a 
transient field or a
+  detachable model.
+- A change to the serialized form — a new field type, a different collection 
class, a changed
+  `serialVersionUID` — means pages stored by the previous version can't be 
read back. That is
+  acceptable in a major release on `master`, never on a maintenance line, and 
is described in
+  the migration guide.
+- A lambda or anonymous class stored in a component has to be serializable; 
Wicket's lambda-based
+  API takes the `Serializable*` interfaces for that reason.
+
+## Accessibility
+
+Components, their markup and the JavaScript that comes with them produce the 
HTML of every
+application that uses them, so their accessibility is the applications' 
accessibility.
+
+- Markup, components and JavaScript that render UI meet WCAG 2.2 at level AA, 
or at least don't
+  make an existing component less accessible than it was.

Review Comment:
   This sets two bars, and an agent will pick the weaker one. Split them by 
case:
   
   ```suggestion
   - New markup, components and JavaScript that render UI meet WCAG 2.2 at 
level AA. A change to
     existing UI leaves it at least as accessible as it was.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,118 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+# Reviewing a change to Apache Wicket
+
+What a review of a pull request checks, whoever does it: a committer, a 
contributor or an agent.
+The conventions for writing a change — format, commits, build, API 
compatibility, Javadoc,
+comments, language and security — are in `AGENTS.md`. A review checks the 
change against those as
+well; this file adds what is easy to miss when a change otherwise looks right.
+
+Most changes touch only a few of the sections below. A section that doesn't 
apply needs no
+comment, but one that does apply needs an answer in the change itself, not a 
promise to follow
+up.
+
+## License compliance
+
+- Every new file carries the ASF license header. Apache RAT checks this during 
the build, so a
+  missing header fails it; files that can't carry one belong in 
`.rat-excludes`, with a reason.
+- A new dependency, or a new version of one, is under a license the ASF 
allows: category A, or
+  category B, which may only be included in binary form, never as source 
copied into the tree.
+  Category X licenses (GPL, AGPL, LGPL and their like) are never allowed. The 
categories are
+  listed at https://www.apache.org/legal/resolved.html.
+- Third-party code, scripts, styles, fonts or images copied into the source 
tree are listed in
+  `LICENSE`, with the license text in `licenses/`. When they end up in a 
published jar, they are
+  listed in `LICENSE-binary` as well. `NOTICE` changes only when the third 
party's own license or
+  NOTICE file requires an attribution there.
+- A Maven dependency is not bundled, so it needs no entry in these files, 
unless it is shaded or
+  copied into a Wicket artifact.
+
+## OSGi and JPMS
+
+Every published module is both an OSGi bundle, built by `maven-bundle-plugin` 
from the
+`osgi.export.package` and `osgi.import.package` properties in its pom, and a 
JPMS module, described
+by its `module-info.java`.
+
+- A package that is added, moved, renamed or removed is exported or dropped in 
both places.
+  `wicket-core` and `wicket-extensions` list their exported packages one by 
one, so a new package
+  there isn't exported until it is added to the list; the other modules export 
by wildcard.
+- A new dependency is a `requires` in `module-info.java`. An optional one is
+  `<optional>true</optional>` in the pom and `requires static` in 
`module-info.java`; the bundle
+  plugin then imports its packages with `resolution:=optional`. Check the 
`Import-Package`
+  header of the built jar's manifest when in doubt.
+- The import version ranges stay usable: a range that excludes a version 
applications commonly
+  run breaks them in an OSGi container even when the build passes.
+
+## Performance
+
+Wicket renders every page by walking its component tree, and stores pages in 
the session and the
+page store, so small costs in core classes multiply.
+
+- A change to a hot path keeps its time complexity and its memory footprint 
per component. Hot
+  paths include `Component` and `ComponentState`, `MarkupContainer` children, 
rendering,
+  markup parsing and loading, request mapping and handling, models, and page 
serialization.
+- A change that makes such a path slower or larger says so in the commit 
message and justifies it,
+  with numbers from `wicket-benchmarks` where it can be measured.
+- A replacement for a library class — a collection, a cache, a parser — keeps 
the complexity of
+  every operation Wicket relies on, not only the common ones. Removing a 
dependency is no reason to
+  give up a performance gain.
+
+## Serialization
+
+Pages are serialized into the page store, and with them every component, 
behavior and model they
+hold.
+
+- A field added to a component, behavior or model adds to the size of every 
stored page that
+  holds one. A field that can be computed or loaded again belongs in a 
transient field or a
+  detachable model.
+- A change to the serialized form — a new field type, a different collection 
class, a changed
+  `serialVersionUID` — means pages stored by the previous version can't be 
read back. That is
+  acceptable in a major release on `master`, never on a maintenance line, and 
is described in
+  the migration guide.
+- A lambda or anonymous class stored in a component has to be serializable; 
Wicket's lambda-based
+  API takes the `Serializable*` interfaces for that reason.
+
+## Accessibility
+
+Components, their markup and the JavaScript that comes with them produce the 
HTML of every
+application that uses them, so their accessibility is the applications' 
accessibility.
+
+- Markup, components and JavaScript that render UI meet WCAG 2.2 at level AA, 
or at least don't
+  make an existing component less accessible than it was.
+- Check in particular: form controls have labels, images have text 
alternatives, roles and ARIA
+  attributes are correct and kept in sync with the state they describe, 
everything that works with
+  a mouse works with a keyboard, focus is not lost or moved unexpectedly by an 
Ajax update, and
+  changes announced only visually are also announced to assistive technology 
where that matters.
+- An example or a test page is not exempt: the examples are what applications 
copy.
+
+## Documentation
+
+- A change users notice — a new feature, a changed default, a removed or 
renamed API, a change in
+  behavior or in dependencies — updates the documentation in the same pull 
request: the Javadoc,
+  the user guide in `wicket-user-guide`, and for anything that breaks or 
changes an existing
+  application, `migration-to-<major>.md` in the root of the branch.
+- A mechanical API change comes with an OpenRewrite recipe in 
`wicket-migration`, as `AGENTS.md`
+  describes.
+- Documentation that the change makes wrong is fixed in the same pull request, 
wherever it is:
+  Javadoc, the user guide, `README.md`, the examples.
+
+## Tests
+
+- A behavior change or a bug fix comes with a test that fails without it.
+- A test class is named `*Test.java`; Surefire runs nothing else, so a 
`*Tests` class or a
+  `Test*` class passes review and never runs.
+- A test sits where `AGENTS.md` says: in the module's `-tests` companion where 
one exists, with
+  its markup next to it in `src/test/java`.

Review Comment:
   Lines 115-116 repeat AGENTS.md:69 almost word for word. Line 117 already 
points to AGENTS.md, which is the better approach for both.
   
   ```suggestion
   - A behavior change or a bug fix comes with a test that fails without it.
   - The test is named and placed as `AGENTS.md` says under "Build and test" 
and "Where code goes".
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to