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]
