gnodet commented on code in PR #2026: URL: https://github.com/apache/maven-resolver/pull/2026#discussion_r3708810102
########## src/site/markdown/api-compatibility.md: ########## @@ -19,93 +19,83 @@ specific language governing permissions and limitations under the License. --> -Maven Resolver exposes three modules for clients and those extending Maven Resolver: -* maven-resolver-api (in short API) -- for clients and those extending it -* maven-resolver-spi (in short SPI) -- for those extending it -* maven-resolver-util (in short Util) -- for client and those extending it +Maven Resolver exposes three modules for client applications and extensions. +Client applications invoke methods in these modules. +Extensions inherit from classes and implement interfaces. -Each module guarantees non-breaking (source and binary) compatibility, as long -clients and extenders obey some rules. If you break any of these rules, you are -prone to breakage, and you are on your own. +* `maven-resolver-api` (API) - Client applications and extensions use this module. +* `maven-resolver-spi` (SPI) - Extensions use this module. +* `maven-resolver-util` (Util) - Client applications and extensions use this module. -## Interface And (Abstract) Class Level Contracts +If you obey specific rules, these modules will be source and binary compatible across minor releases. +If you break these rules, your code can break when you update these modules. -In source, we use two important Javadoc tags to mark intent: -* `@noextend` -- classes (or interfaces) carrying this tag MUST NOT be extended -* `@noimplement` -- interfaces carrying this tag MUST NOT be directly or indirectly implemented, - UNLESS the Javadoc of given interface points to an abstract support class that makes indirect - implementation possible. +## Interface And (Abstract) Class Level Contracts -Examples: +We use two Javadoc tags in the source code to mark intent: +* `@noextend` - You must not extend classes or interfaces with this tag. +* `@noimplement` - You must not implement interfaces with this tag directly or indirectly. -* `RepositorySystem` interface. It carries both `@noextend` and `@noimplement` tags. This interface - MUST NOT be extended nor implemented. This is a component interface, that is usually injected into - client application. -* `TransferListener` interface. It carries both `@noextend` and `@noimplement` tags, but Javadoc - points at `AbstractTransferListener` as extension point. Hence, clients are NOT allowed to extend - this interface, nor to directly implement it, but, if custom listener is needed, it is warmly - advised to extend the given abstract class. This way we can protect you from future breakage. +If the Javadoc points to an abstract support class, you can implement the `@noimplement` interface indirectly. -## Package Level Contracts +Examples: -Maven Resolver implements customary habit to name packages NOT meant to be accessed by clients. -If a Java package contains following names: +The `RepositorySystem` interface has the `@noextend` tag and the `@noimplement` tag. +You must not extend or implement this interface. +The `RepositorySystem` interface is a component interface. +Client applications usually receive this interface through dependency injection. -* `impl` -* `internal` +The `TransferListener` interface has the `@noextend` tag and the `@noimplement` tag. +The Javadoc points to the `AbstractTransferListener` abstract class. +You must not extend or implement the `TransferListener` interface directly. +If you need a custom listener, you must extend the `AbstractTransferListener` abstract class. Review Comment: The original says extending `AbstractTransferListener` is "warmly advised" (a recommendation). The rewrite changes this to "you must extend" (a mandate), which alters the contract — the original left room for other approaches like composition or delegation. ```suggestion If you need a custom listener, extend the `AbstractTransferListener` abstract class. ``` Dropping "must" keeps the recommendation without overstating the constraint. ########## src/site/markdown/api-compatibility.md: ########## @@ -19,93 +19,83 @@ specific language governing permissions and limitations under the License. --> -Maven Resolver exposes three modules for clients and those extending Maven Resolver: -* maven-resolver-api (in short API) -- for clients and those extending it -* maven-resolver-spi (in short SPI) -- for those extending it -* maven-resolver-util (in short Util) -- for client and those extending it +Maven Resolver exposes three modules for client applications and extensions. +Client applications invoke methods in these modules. +Extensions inherit from classes and implement interfaces. -Each module guarantees non-breaking (source and binary) compatibility, as long -clients and extenders obey some rules. If you break any of these rules, you are -prone to breakage, and you are on your own. +* `maven-resolver-api` (API) - Client applications and extensions use this module. +* `maven-resolver-spi` (SPI) - Extensions use this module. +* `maven-resolver-util` (Util) - Client applications and extensions use this module. -## Interface And (Abstract) Class Level Contracts +If you obey specific rules, these modules will be source and binary compatible across minor releases. +If you break these rules, your code can break when you update these modules. -In source, we use two important Javadoc tags to mark intent: -* `@noextend` -- classes (or interfaces) carrying this tag MUST NOT be extended -* `@noimplement` -- interfaces carrying this tag MUST NOT be directly or indirectly implemented, - UNLESS the Javadoc of given interface points to an abstract support class that makes indirect - implementation possible. +## Interface And (Abstract) Class Level Contracts -Examples: +We use two Javadoc tags in the source code to mark intent: +* `@noextend` - You must not extend classes or interfaces with this tag. +* `@noimplement` - You must not implement interfaces with this tag directly or indirectly. -* `RepositorySystem` interface. It carries both `@noextend` and `@noimplement` tags. This interface - MUST NOT be extended nor implemented. This is a component interface, that is usually injected into - client application. -* `TransferListener` interface. It carries both `@noextend` and `@noimplement` tags, but Javadoc - points at `AbstractTransferListener` as extension point. Hence, clients are NOT allowed to extend - this interface, nor to directly implement it, but, if custom listener is needed, it is warmly - advised to extend the given abstract class. This way we can protect you from future breakage. +If the Javadoc points to an abstract support class, you can implement the `@noimplement` interface indirectly. -## Package Level Contracts +Examples: -Maven Resolver implements customary habit to name packages NOT meant to be accessed by clients. -If a Java package contains following names: +The `RepositorySystem` interface has the `@noextend` tag and the `@noimplement` tag. +You must not extend or implement this interface. +The `RepositorySystem` interface is a component interface. +Client applications usually receive this interface through dependency injection. -* `impl` -* `internal` +The `TransferListener` interface has the `@noextend` tag and the `@noimplement` tag. +The Javadoc points to the `AbstractTransferListener` abstract class. +You must not extend or implement the `TransferListener` interface directly. +If you need a custom listener, you must extend the `AbstractTransferListener` abstract class. +This abstract class protects your code from future breakages. -That Java package is meant as "internal" and does NOT offer guarantees of compatibility as API is. You -may use classes from these packages, but again, you are on your own to deal with (binary or source) -breakages. If you think a class from such package should be "pulled out" and made part of SPI or -maybe API, better inform us via [JIRA](https://issues.apache.org/jira/projects/MRESOLVER): create a -ticket and let's discuss. +## Package Level Contracts -As a side note, the count of those names in Java package is directly proportional to possibility of -breaking changes: the more, the larger the possibility of breakage even in minor releases. +Maven Resolver identifies internal Java packages with the words `impl` and `internal`. +These internal packages do not guarantee compatibility between releases. +If you use classes from these packages, you must fix source breakages and binary breakages yourself. +You can request to move a class to the API or the SPI through a ticket on [GitHub](https://github.com/apache/maven-resolver/issues). ## Version Level Contracts -Maven Resolver does NOT use "semantic versioning", but still tries at best to reflect contained -changes using version number. We use "major.minor.patch" versioning on resolver with following -semantics: - -* On major version change, one should NOT expect any backward compatibility. -* On minor version change, we ENSURE backward compatibility for those "exposed" 3 modules: API, - SPI and Util. Still, there are examples when we failed to do so, usually driven by new - features. +Maven Resolver does not use "semantic versioning". +However, Maven Resolver uses a "major.minor.patch" version format to indicate changes. +Major version changes do not provide backward compatibility. +The API, SPI, and Util modules should be backwards compatible across minor version changes. Review Comment: Minor: the original uses "we ENSURE backward compatibility" (capitalized for emphasis — a strong project commitment). The rewrite downgrades this to "should be backwards compatible" which reads as an aspiration rather than a promise. Both are immediately followed by the caveat about past violations, so the practical meaning is similar, but you may want to preserve the intended strength (e.g. "we ensure backward compatibility"). ########## src/site/markdown/api-compatibility.md: ########## @@ -19,93 +19,83 @@ specific language governing permissions and limitations under the License. --> -Maven Resolver exposes three modules for clients and those extending Maven Resolver: -* maven-resolver-api (in short API) -- for clients and those extending it -* maven-resolver-spi (in short SPI) -- for those extending it -* maven-resolver-util (in short Util) -- for client and those extending it +Maven Resolver exposes three modules for client applications and extensions. +Client applications invoke methods in these modules. +Extensions inherit from classes and implement interfaces. -Each module guarantees non-breaking (source and binary) compatibility, as long -clients and extenders obey some rules. If you break any of these rules, you are -prone to breakage, and you are on your own. +* `maven-resolver-api` (API) - Client applications and extensions use this module. +* `maven-resolver-spi` (SPI) - Extensions use this module. +* `maven-resolver-util` (Util) - Client applications and extensions use this module. -## Interface And (Abstract) Class Level Contracts +If you obey specific rules, these modules will be source and binary compatible across minor releases. +If you break these rules, your code can break when you update these modules. -In source, we use two important Javadoc tags to mark intent: -* `@noextend` -- classes (or interfaces) carrying this tag MUST NOT be extended -* `@noimplement` -- interfaces carrying this tag MUST NOT be directly or indirectly implemented, - UNLESS the Javadoc of given interface points to an abstract support class that makes indirect - implementation possible. +## Interface And (Abstract) Class Level Contracts -Examples: +We use two Javadoc tags in the source code to mark intent: +* `@noextend` - You must not extend classes or interfaces with this tag. +* `@noimplement` - You must not implement interfaces with this tag directly or indirectly. -* `RepositorySystem` interface. It carries both `@noextend` and `@noimplement` tags. This interface - MUST NOT be extended nor implemented. This is a component interface, that is usually injected into - client application. -* `TransferListener` interface. It carries both `@noextend` and `@noimplement` tags, but Javadoc - points at `AbstractTransferListener` as extension point. Hence, clients are NOT allowed to extend - this interface, nor to directly implement it, but, if custom listener is needed, it is warmly - advised to extend the given abstract class. This way we can protect you from future breakage. +If the Javadoc points to an abstract support class, you can implement the `@noimplement` interface indirectly. -## Package Level Contracts +Examples: -Maven Resolver implements customary habit to name packages NOT meant to be accessed by clients. -If a Java package contains following names: +The `RepositorySystem` interface has the `@noextend` tag and the `@noimplement` tag. +You must not extend or implement this interface. +The `RepositorySystem` interface is a component interface. +Client applications usually receive this interface through dependency injection. -* `impl` -* `internal` +The `TransferListener` interface has the `@noextend` tag and the `@noimplement` tag. +The Javadoc points to the `AbstractTransferListener` abstract class. +You must not extend or implement the `TransferListener` interface directly. +If you need a custom listener, you must extend the `AbstractTransferListener` abstract class. +This abstract class protects your code from future breakages. -That Java package is meant as "internal" and does NOT offer guarantees of compatibility as API is. You -may use classes from these packages, but again, you are on your own to deal with (binary or source) -breakages. If you think a class from such package should be "pulled out" and made part of SPI or -maybe API, better inform us via [JIRA](https://issues.apache.org/jira/projects/MRESOLVER): create a -ticket and let's discuss. +## Package Level Contracts -As a side note, the count of those names in Java package is directly proportional to possibility of -breaking changes: the more, the larger the possibility of breakage even in minor releases. +Maven Resolver identifies internal Java packages with the words `impl` and `internal`. +These internal packages do not guarantee compatibility between releases. +If you use classes from these packages, you must fix source breakages and binary breakages yourself. +You can request to move a class to the API or the SPI through a ticket on [GitHub](https://github.com/apache/maven-resolver/issues). ## Version Level Contracts -Maven Resolver does NOT use "semantic versioning", but still tries at best to reflect contained -changes using version number. We use "major.minor.patch" versioning on resolver with following -semantics: - -* On major version change, one should NOT expect any backward compatibility. -* On minor version change, we ENSURE backward compatibility for those "exposed" 3 modules: API, - SPI and Util. Still, there are examples when we failed to do so, usually driven by new - features. +Maven Resolver does not use "semantic versioning". +However, Maven Resolver uses a "major.minor.patch" version format to indicate changes. +Major version changes do not provide backward compatibility. +The API, SPI, and Util modules should be backwards compatible across minor version changes. +However, we have violated this rule in the past, usually to support new features. -In any of three version changes above, in areas where we do not offer guarantees, everything -can happen. +Maven Resolver does not guarantee compatibility for internal modules. +Internal modules can change in any version update. ## Outside of Maven -Applications integrating Maven Resolver outside of Maven has really simple job: all they have to -ensure is that API, SPI, Util and the rest of resolver (impl, basic-connector and transports) -have all same versions, and they can rely on these backward compatibility contracts as explained -above. +Applications can use Maven Resolver outside of Maven. +These applications must use the same version for all Maven Resolver modules. +For example, the API, SPI, Util, `impl`, `basic-connector`, and transports must share the same version. +If the versions match, the applications can rely on the compatibility guarantees. ## Inside of Maven -Historically, Maven 3.1 provided API, SPI -and Impl from its own embedded resolver, while Util and Connector, if some plugin or extension -depended on them, were resolved separately. This meant that a plugin could work with different versions -of API, SPI, Impl or Connector. Because the Resolver API was "frozen" for too long a time, this was essentially -not a problem, but still weird. +In the past, Maven 3.1 provided the API, SPI, and `impl` modules from an embedded resolver. +Plugins resolved the Util and Connector modules separately. +Therefore, plugins used different versions of these modules. +The static API prevented major problems. -This changes in Maven 3.9+: Maven starting with version 3.9.0 will provide API, SPI, Impl, -**and Util and Connector**. Reason for this change is that Impl and Connector bundled in Maven -implement things from both API and SPI, and there was a binary incompatible change between -Resolver 1.8.0 and previous versions. +Maven 3.9.0 provides the API, SPI, `impl`, Util, and Connector modules. +The bundled `impl` and Connector modules implement the API and the SPI. +A binary incompatibility occurred between Maven Resolver 1.8.0 and previous versions. +Because of this incompatibility, Maven 3.9.0 bundles all modules to ensure stability. -Most Resolver users should not be affected by this change. +This change does not affect most Maven Resolver users. -The binary incompatible change happened in the SPI class `RepositoryLayout` as part of work done for -[MRESOLVER-230](https://issues.apache.org/jira/browse/MRESOLVER-230), and affects both, Connector -and Impl. +The binary incompatibility occurred in the `RepositoryLayout` SPI class for [MRESOLVER-230](https://issues.apache.org/jira/browse/MRESOLVER-230). +This incompatibility affects the Connector module and the `impl` module. ## Backward Compatibility Checks -To ensure backward compatibility, starting from 1.9.0 Maven Resolver uses -[JApiCmp](https://siom79.github.io/japicmp/MavenPlugin.html), -with two executions (for source and binary level checks). The plugin is enabled on 3 modules of -Resolver mentioned at page top: API, SPI and Util. For "baseline" we use version 1.8.0. +Maven Resolver uses [JApiCmp](https://siom79.github.io/japicmp/MavenPlugin.html) to verify backward compatibility. +Maven Resolver 1.9.0 runs this plugin twice to verify source compatibility and binary compatibility. Review Comment: The original says "starting from 1.9.0 Maven Resolver uses [JApiCmp]" — meaning version 1.9.0 **and all subsequent versions**. The rewrite reads as specific to 1.9.0 only. Consider preserving the temporal scope: ```suggestion Starting with version 1.9.0, Maven Resolver runs this plugin twice to verify source compatibility and binary compatibility. ``` -- 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]
