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]