[
https://issues.apache.org/jira/browse/HADOOP-20002?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jose Luis López updated HADOOP-20002:
-------------------------------------
Description:
Sub-task of HADOOP-19395 (preparation on trunk; no namespace change).
h3. Why
The javax → jakarta switch touches thousands of lines across 44 modules. Two
tools make it measurable and reviewable:
* an inventory that says what has to change, where, and how much is left;
* a rewrite that does the mechanical part the same way every time, so reviewers
check the rules and the manual fixes rather than every changed import.
Neither changes any code on trunk.
h3. 1. Inventory script
Add {{dev-support/bin/javax-inventory}} (Python 3, standard library only, like
{{checkcompatibility.py}}). It scans every git-tracked text file and classifies
each {{javax}} reference:
* *ee*: Java EE APIs that moved to {{jakarta}} (servlet, JAX-RS, JAXB, inject,
activation, JSON-P…);
* *jetty-ee8*: Jetty 12's javax environment types, which become ee10/ee11;
* *jsr305*, *jdk* and *stays*: {{javax}} names that do not change
({{javax.annotation.Nullable}}, {{javax.net}}, {{javax.crypto}}, JCache…);
* *unknown*: for review by hand.
It covers imports, fully-qualified names, string literals, javadoc, POMs
(including shade relocations), resources, the slash form ({{javax/servlet}})
and {{META-INF/services}}. It reports, per module:
* main, test and other files affected;
* the Public/LimitedPrivate classes using EE types, from class- or
package-level {{@InterfaceAudience}};
* the third-party artifacts bound to javax;
* the module dependency layers, which give the order of the switch.
It writes {{report.md}} and {{usages.csv}}.
On the HADOOP-19972 branch it finds 3,368 EE references, 140 Jetty ee8
references, 86 Public/LimitedPrivate classes and 30 javax-bound managed
artifacts.
h3. 2. Reproducible rewrite
Add the rules and a script that apply the mechanical part of the switch to a
working tree:
* package renames ({{javax.servlet}} → {{jakarta.servlet}}, {{javax.ws.rs}} →
{{jakarta.ws.rs}}, {{javax.xml.bind}} → {{jakarta.xml.bind}}…) in Java sources,
resources, string literals and POM shade configurations;
* {{org.eclipse.jetty.ee8}} → {{org.eclipse.jetty.ee10}};
* never touching the names that stay ({{javax.net}}, {{javax.crypto}},
{{javax.security.auth}}, jsr305, JCache).
The rewrite is not run on trunk. It produces the mechanical change for the
HADOOP-19395 feature branch, where the switch sub-tasks add the dependency
changes and the manual fixes.
h3. Documentation
A short section in {{dev-support/README.md}}: how to run both tools, how to
read the report, and what the rewrite does and does not change.
h3. Done when
* {{dev-support/bin/javax-inventory}} runs on trunk with no network access and
produces the report.
* The rewrite, run on a trunk checkout, produces a diff that changes only the
names it should, with a classification check showing no {{jdk}}, {{jsr305}} or
{{stays}} name was renamed.
* Both are documented in {{dev-support/README.md}}.
h3. Out of scope
* Applying the rewrite to trunk, and the dependency changes: the switch
sub-tasks of HADOOP-19395.
* A CI check that fails on new javax EE imports: it only makes sense once the
switch is done, so it belongs to the last switch sub-task.
> Add a javax inventory script and a reproducible javax → jakarta rewrite to
> dev-support
> --------------------------------------------------------------------------------------
>
> Key: HADOOP-20002
> URL: https://issues.apache.org/jira/browse/HADOOP-20002
> Project: Hadoop Common
> Issue Type: Sub-task
> Reporter: Jose Luis López
> Priority: Critical
>
> Sub-task of HADOOP-19395 (preparation on trunk; no namespace change).
> h3. Why
> The javax → jakarta switch touches thousands of lines across 44 modules. Two
> tools make it measurable and reviewable:
> * an inventory that says what has to change, where, and how much is left;
> * a rewrite that does the mechanical part the same way every time, so
> reviewers check the rules and the manual fixes rather than every changed
> import.
> Neither changes any code on trunk.
> h3. 1. Inventory script
> Add {{dev-support/bin/javax-inventory}} (Python 3, standard library only,
> like {{checkcompatibility.py}}). It scans every git-tracked text file and
> classifies each {{javax}} reference:
> * *ee*: Java EE APIs that moved to {{jakarta}} (servlet, JAX-RS, JAXB,
> inject, activation, JSON-P…);
> * *jetty-ee8*: Jetty 12's javax environment types, which become ee10/ee11;
> * *jsr305*, *jdk* and *stays*: {{javax}} names that do not change
> ({{javax.annotation.Nullable}}, {{javax.net}}, {{javax.crypto}}, JCache…);
> * *unknown*: for review by hand.
> It covers imports, fully-qualified names, string literals, javadoc, POMs
> (including shade relocations), resources, the slash form ({{javax/servlet}})
> and {{META-INF/services}}. It reports, per module:
> * main, test and other files affected;
> * the Public/LimitedPrivate classes using EE types, from class- or
> package-level {{@InterfaceAudience}};
> * the third-party artifacts bound to javax;
> * the module dependency layers, which give the order of the switch.
> It writes {{report.md}} and {{usages.csv}}.
> On the HADOOP-19972 branch it finds 3,368 EE references, 140 Jetty ee8
> references, 86 Public/LimitedPrivate classes and 30 javax-bound managed
> artifacts.
> h3. 2. Reproducible rewrite
> Add the rules and a script that apply the mechanical part of the switch to a
> working tree:
> * package renames ({{javax.servlet}} → {{jakarta.servlet}}, {{javax.ws.rs}} →
> {{jakarta.ws.rs}}, {{javax.xml.bind}} → {{jakarta.xml.bind}}…) in Java
> sources, resources, string literals and POM shade configurations;
> * {{org.eclipse.jetty.ee8}} → {{org.eclipse.jetty.ee10}};
> * never touching the names that stay ({{javax.net}}, {{javax.crypto}},
> {{javax.security.auth}}, jsr305, JCache).
> The rewrite is not run on trunk. It produces the mechanical change for the
> HADOOP-19395 feature branch, where the switch sub-tasks add the dependency
> changes and the manual fixes.
> h3. Documentation
> A short section in {{dev-support/README.md}}: how to run both tools, how to
> read the report, and what the rewrite does and does not change.
> h3. Done when
> * {{dev-support/bin/javax-inventory}} runs on trunk with no network access
> and produces the report.
> * The rewrite, run on a trunk checkout, produces a diff that changes only the
> names it should, with a classification check showing no {{jdk}}, {{jsr305}}
> or {{stays}} name was renamed.
> * Both are documented in {{dev-support/README.md}}.
> h3. Out of scope
> * Applying the rewrite to trunk, and the dependency changes: the switch
> sub-tasks of HADOOP-19395.
> * A CI check that fails on new javax EE imports: it only makes sense once the
> switch is done, so it belongs to the last switch sub-task.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
