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


##########
REVIEW.md:
##########
@@ -0,0 +1,149 @@
+<!--
+   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.
+
+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.
+
+## License compliance
+
+Applies when the change adds a file, adds or upgrades a dependency, or copies 
third-party material
+into the source tree.
+
+- 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.
+- 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.
+
+## Security
+
+Applies when the change writes a value into markup, JavaScript, a URL or a 
header; reads request
+input; adds or changes a listener, a resource or a request mapper; or touches 
encryption, the page
+store or authorization. `SECURITY.md` states what Wicket trusts: a change 
keeps to that model, or
+changes `SECURITY.md` in the same pull request.
+
+- A component escapes the model data it renders while `escapeModelStrings` is 
on. A bundle value
+  is escaped for the context it is written into: `Strings#escapeMarkup` for 
markup,
+  `JavaScriptUtils#escapeQuotes` for a JavaScript literal. `escapeMarkup` 
covers element text and
+  quoted attribute values only; a value inside `<script>` or `<style>`, in an 
unquoted attribute
+  or in a URL needs an encoding for that context.
+- Request parameters, headers, cookies and uploaded file names are untrusted. 
The host, port and
+  scheme come from the container, and `X-Forwarded-*` headers count only 
through
+  `XForwardedRequestWrapperFactory`.
+- A new listener is invoked through the request cycle, so 
`ResourceIsolationRequestCycleListener`
+  and `Component#canCallListener` apply to it, and it runs only on an enabled, 
visible component.
+- A resource served from the classpath passes `IPackageResourceGuard`, and a 
path built from
+  request input stays inside the directory it was meant for.
+- Encryption uses an authenticated scheme and a `SecureRandom`; `CryptoMapper` 
is the only place
+  that encrypts deterministically. Keys, session ids and stored values stay 
out of logs and out of
+  the error pages rendered in `DEPLOYMENT` mode.
+- Nothing deserializes data a client can supply.
+- A fix for an unreleased vulnerability keeps that out of its title, commit 
message and branch
+  name, as `AGENTS.md` describes.

Review Comment:
   This reads as if a public pull request for an unreleased vulnerability is 
fine as long as its title, commit message and branch name are vague. 
`AGENTS.md` and `SECURITY.md` keep it out of a pull request altogether, and a 
reviewer who spots a vulnerability in code the change touches needs to know 
where it goes:
   
   ```suggestion
   - A suspected vulnerability, in the change or in code it touches, is 
reported to
     [email protected] and not mentioned in the pull request. A fix for an 
unreleased
     vulnerability is not prepared in a public pull request; see `SECURITY.md`.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,149 @@
+<!--
+   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.
+
+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 Comment:
   As written, a reviewer, and certainly an agent following this file 
literally, records a possible vulnerability as "a finding naming the file and 
line" and has it resolved in the same pull request: a public comment describing 
the vulnerability. `SECURITY.md` asks not to report vulnerabilities through 
pull requests. An explicit exception here:
   
   ```suggestion
   resolved in the change itself, in the same pull request. A finding that may 
be a vulnerability
   is the exception: it never goes into a review comment, but to 
[email protected], as
   `SECURITY.md` describes.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,149 @@
+<!--
+   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.
+
+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.
+
+## License compliance
+
+Applies when the change adds a file, adds or upgrades a dependency, or copies 
third-party material
+into the source tree.
+
+- 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.
+- 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.
+
+## Security
+
+Applies when the change writes a value into markup, JavaScript, a URL or a 
header; reads request
+input; adds or changes a listener, a resource or a request mapper; or touches 
encryption, the page
+store or authorization. `SECURITY.md` states what Wicket trusts: a change 
keeps to that model, or
+changes `SECURITY.md` in the same pull request.
+
+- A component escapes the model data it renders while `escapeModelStrings` is 
on. A bundle value
+  is escaped for the context it is written into: `Strings#escapeMarkup` for 
markup,
+  `JavaScriptUtils#escapeQuotes` for a JavaScript literal. `escapeMarkup` 
covers element text and
+  quoted attribute values only; a value inside `<script>` or `<style>`, in an 
unquoted attribute
+  or in a URL needs an encoding for that context.
+- Request parameters, headers, cookies and uploaded file names are untrusted. 
The host, port and
+  scheme come from the container, and `X-Forwarded-*` headers count only 
through
+  `XForwardedRequestWrapperFactory`.
+- A new listener is invoked through the request cycle, so 
`ResourceIsolationRequestCycleListener`
+  and `Component#canCallListener` apply to it, and it runs only on an enabled, 
visible component.
+- A resource served from the classpath passes `IPackageResourceGuard`, and a 
path built from
+  request input stays inside the directory it was meant for.
+- Encryption uses an authenticated scheme and a `SecureRandom`; `CryptoMapper` 
is the only place
+  that encrypts deterministically. Keys, session ids and stored values stay 
out of logs and out of
+  the error pages rendered in `DEPLOYMENT` mode.
+- Nothing deserializes data a client can supply.
+- A fix for an unreleased vulnerability keeps that out of its title, commit 
message and branch
+  name, as `AGENTS.md` describes.
+
+## 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 in a pom. 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
+
+Applies when the change touches a hot path: `Component` and `ComponentState`, 
`MarkupContainer`
+children, rendering, markup parsing and loading, request mapping and handling, 
models, and page
+serialization. Wicket walks the component tree for every page it renders and 
stores pages in the
+session and the page store, so small costs in these classes multiply.
+
+- A hot path keeps its time complexity and its memory footprint per component.
+- A change that makes a hot 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.
+
+## Serialization
+
+Applies when a component, behavior or model gains or changes a field, or 
stores a lambda or
+anonymous class. 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. Such a
+  change lands in a major release on `master` and is described in the 
migration guide; a
+  maintenance line keeps the serialized form it was released with.
+- 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
+
+Applies when the change touches markup, a component or JavaScript that renders 
UI, examples and
+test pages included. Components produce the HTML of every application that 
uses them, so their

Review Comment:
   Test pages in the test modules are never seen by a user, and are often 
deliberately minimal or deliberately broken (an input without a label, an image 
without `alt`) because that's what the test exercises. Holding them to WCAG AA 
doesn't help anyone and will be ignored in practice, which weakens the rest of 
the list. "They are what applications copy" holds for the examples, so I'd keep 
the bar there:
   
   ```suggestion
   Applies when the change touches markup, a component or JavaScript that 
renders UI, examples
   included. Components produce the HTML of every application that uses them, 
so their
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,149 @@
+<!--
+   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.
+
+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.
+
+## License compliance
+
+Applies when the change adds a file, adds or upgrades a dependency, or copies 
third-party material
+into the source tree.
+
+- 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.
+- 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.
+
+## Security
+
+Applies when the change writes a value into markup, JavaScript, a URL or a 
header; reads request
+input; adds or changes a listener, a resource or a request mapper; or touches 
encryption, the page
+store or authorization. `SECURITY.md` states what Wicket trusts: a change 
keeps to that model, or
+changes `SECURITY.md` in the same pull request.
+
+- A component escapes the model data it renders while `escapeModelStrings` is 
on. A bundle value
+  is escaped for the context it is written into: `Strings#escapeMarkup` for 
markup,
+  `JavaScriptUtils#escapeQuotes` for a JavaScript literal. `escapeMarkup` 
covers element text and
+  quoted attribute values only; a value inside `<script>` or `<style>`, in an 
unquoted attribute
+  or in a URL needs an encoding for that context.
+- Request parameters, headers, cookies and uploaded file names are untrusted. 
The host, port and
+  scheme come from the container, and `X-Forwarded-*` headers count only 
through
+  `XForwardedRequestWrapperFactory`.
+- A new listener is invoked through the request cycle, so 
`ResourceIsolationRequestCycleListener`
+  and `Component#canCallListener` apply to it, and it runs only on an enabled, 
visible component.
+- A resource served from the classpath passes `IPackageResourceGuard`, and a 
path built from
+  request input stays inside the directory it was meant for.
+- Encryption uses an authenticated scheme and a `SecureRandom`; `CryptoMapper` 
is the only place
+  that encrypts deterministically. Keys, session ids and stored values stay 
out of logs and out of
+  the error pages rendered in `DEPLOYMENT` mode.
+- Nothing deserializes data a client can supply.
+- A fix for an unreleased vulnerability keeps that out of its title, commit 
message and branch
+  name, as `AGENTS.md` describes.
+
+## 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 in a pom. 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
+
+Applies when the change touches a hot path: `Component` and `ComponentState`, 
`MarkupContainer`
+children, rendering, markup parsing and loading, request mapping and handling, 
models, and page
+serialization. Wicket walks the component tree for every page it renders and 
stores pages in the
+session and the page store, so small costs in these classes multiply.
+
+- A hot path keeps its time complexity and its memory footprint per component.
+- A change that makes a hot 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.
+
+## Serialization
+
+Applies when a component, behavior or model gains or changes a field, or 
stores a lambda or
+anonymous class. 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. Such a
+  change lands in a major release on `master` and is described in the 
migration guide; a
+  maintenance line keeps the serialized form it was released with.

Review Comment:
   This is new policy rather than a review check: nothing in `AGENTS.md` or 
`SECURITY.md` says a maintenance line keeps its serialized form, and bug fixes 
on the maintenance lines have changed component fields before. As a rule it's 
too strict. It would block ordinary fixes on 10.x and 11.x, and "a new field 
type" reads as if adding a field breaks reading back, which it doesn't with a 
fixed `serialVersionUID`. If you want a rule like this, could you raise it on 
dev@ first, and drop it from this file until there's agreement?
   
   ```suggestion
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,149 @@
+<!--
+   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.
+
+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.
+
+## License compliance
+
+Applies when the change adds a file, adds or upgrades a dependency, or copies 
third-party material
+into the source tree.
+
+- 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.
+- 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.
+
+## Security
+
+Applies when the change writes a value into markup, JavaScript, a URL or a 
header; reads request
+input; adds or changes a listener, a resource or a request mapper; or touches 
encryption, the page
+store or authorization. `SECURITY.md` states what Wicket trusts: a change 
keeps to that model, or
+changes `SECURITY.md` in the same pull request.
+
+- A component escapes the model data it renders while `escapeModelStrings` is 
on. A bundle value
+  is escaped for the context it is written into: `Strings#escapeMarkup` for 
markup,
+  `JavaScriptUtils#escapeQuotes` for a JavaScript literal. `escapeMarkup` 
covers element text and
+  quoted attribute values only; a value inside `<script>` or `<style>`, in an 
unquoted attribute
+  or in a URL needs an encoding for that context.
+- Request parameters, headers, cookies and uploaded file names are untrusted. 
The host, port and
+  scheme come from the container, and `X-Forwarded-*` headers count only 
through
+  `XForwardedRequestWrapperFactory`.
+- A new listener is invoked through the request cycle, so 
`ResourceIsolationRequestCycleListener`
+  and `Component#canCallListener` apply to it, and it runs only on an enabled, 
visible component.
+- A resource served from the classpath passes `IPackageResourceGuard`, and a 
path built from
+  request input stays inside the directory it was meant for.
+- Encryption uses an authenticated scheme and a `SecureRandom`; `CryptoMapper` 
is the only place
+  that encrypts deterministically. Keys, session ids and stored values stay 
out of logs and out of
+  the error pages rendered in `DEPLOYMENT` mode.
+- Nothing deserializes data a client can supply.
+- A fix for an unreleased vulnerability keeps that out of its title, commit 
message and branch
+  name, as `AGENTS.md` describes.
+
+## 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 in a pom. 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
+
+Applies when the change touches a hot path: `Component` and `ComponentState`, 
`MarkupContainer`
+children, rendering, markup parsing and loading, request mapping and handling, 
models, and page
+serialization. Wicket walks the component tree for every page it renders and 
stores pages in the
+session and the page store, so small costs in these classes multiply.
+
+- A hot path keeps its time complexity and its memory footprint per component.
+- A change that makes a hot 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.
+
+## Serialization
+
+Applies when a component, behavior or model gains or changes a field, or 
stores a lambda or
+anonymous class. 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. Such a
+  change lands in a major release on `master` and is described in the 
migration guide; a
+  maintenance line keeps the serialized form it was released with.
+- 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
+
+Applies when the change touches markup, a component or JavaScript that renders 
UI, examples and
+test pages included. Components produce the HTML of every application that 
uses them, so their
+accessibility is the applications' accessibility.
+
+- 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.
+- 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.
+- Examples and test pages meet the same bar: they are what applications copy.

Review Comment:
   Same as above: examples, not test pages.
   
   ```suggestion
   - Examples meet the same bar: they are what applications copy.
   ```



##########
REVIEW.md:
##########
@@ -0,0 +1,149 @@
+<!--
+   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.

Review Comment:
   The list of `AGENTS.md` sections is already incomplete: it leaves out "Where 
code goes" and "Poms", and it will drift further as sections are added. The 
reference alone does the job:
   
   ```suggestion
   The conventions for writing a change 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.
   ```



##########
AGENTS.md:
##########
@@ -101,10 +104,10 @@ header — copy it when you add one.
 - Quiet is not permission. Changing or removing public API on `master` is 
allowed but not free:
   it needs a justification in the commit message, and where the old member can 
survive next to
   the new one, deprecate it rather than remove it.
-- An API change owes users a migration path. Add an OpenRewrite recipe to
+- A change that breaks or changes an existing application owes users a 
migration path: an entry
+  in `migration-to-<major>.md` in the root of the branch, and an OpenRewrite 
recipe in
   `wicket-migration/src/main/resources/META-INF/rewrite/wicket.yml` where the 
change is
-  mechanical, and draft the migration-guide wording in the commit message or 
the pull request
-  description — the guide itself lives on the wiki, where only a human can put 
it.
+  mechanical, both in the same commit.

Review Comment:
   Do we want to maintain migration documents for several versions on several 
branches at the same time? "In the root of the branch" means a change 
cherry-picked down gets its entry in a different file on every line, as #1866 
did this week in `migration-to-10.md` on 10.x and `migration-to-11.md` on 11.x. 
The copies already drift: the 11.1.0 entry is in `migration-to-11.md` on 
wicket-11.x but not in the one on `master`.
   
   I'd rather keep all migration documents on `master` and keep them up to date 
there. Breaking changes only land on `master` anyway, and a behaviour change in 
a maintenance release can get its entry in that version's guide on `master`. 
The rule would then point at `master` instead of the root of the branch.



##########
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 handing a change over, and when reviewing a pull request, apply every 
section of
+  `REVIEW.md` the change triggers: licensing, security, OSGi and JPMS, 
performance,
+  serialization, accessibility, documentation and tests.

Review Comment:
   This list repeats the section headings of `REVIEW.md`, and has to be kept in 
step with them by hand. "Every section the change triggers" already says it:
   
   ```suggestion
   - Before handing a change over, and when reviewing a pull request, apply 
every section of
     `REVIEW.md` the change triggers.
   ```



-- 
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