Claudenw commented on code in PR #170: URL: https://github.com/apache/cassandra-website/pull/170#discussion_r1374314730
########## site-content/source/modules/ROOT/pages/development/dependencies.adoc: ########## Review Comment: The POM FIle Types section does not make sense where it is now. As it is at the same level as the 4.2 and pre-4.2 sections it would appear to apply to both, however, it mentions files that are only in the pre-4.2 code. I think that a section for the POMs found in each section would be cleaner and easier to understand. ########## site-content/source/modules/ROOT/pages/development/dependencies.adoc: ########## @@ -2,20 +2,45 @@ == Dependency Management -Managing libraries for Cassandra is a bit less straight forward compared -to other projects, as the build process is based on ant, maven and -manually managed jars. Make sure to follow the steps below carefully and -pay attention to any emerging issues in the `ci` and reported related -issues on Jira/ML, in case of any project dependency changes. +New dependencies should not be included without community consensus first being +obtained via a `[DISCUSS]` thread on the [email protected] mailing list. As Cassandra is an Apache product, all included libraries must follow Apache's https://www.apache.org/legal/resolved.html[software license requirements]. -=== Required steps to add or update libraries +=== Dependency management in Cassandra 4.2 and onwards + +In Cassandra 4.2 and onwards, dependencies are managed in Maven POM templates +in `.build/*-template.xml`. These templates are processed into valid Maven POMs +with the `ant write-poms` task and copied to `build/*.pom`. + +The following POMs from `build.xml` have been migrated to templates: +* `parent-pom` is now at `.build/parent-pom-template.xml` +* `all-pom` is now at `.build/cassandra-deps-template.xml` +* `build-deps-pom` is now at `.build/cassandra-build-deps-template.xml` Review Comment: This block does not seem to render correctly in the github viewer. That may be an artifact of the viewer or there may be a need for a blank line to separate the bulleted list from the proceeding paragraph. However, I think the sentences should be changed to read: `X is now Y` rather than `X is now at Y` as the later sounds like a file with the name `Y` will be found in the directory. ########## site-content/source/modules/ROOT/pages/development/dependencies.adoc: ########## @@ -12,10 +12,38 @@ As Cassandra is an Apache product, all included libraries must follow Apache's https://www.apache.org/legal/resolved.html[software license requirements]. -=== Required steps to add or update libraries +=== Dependency management in Cassandra 4.2 and onwards + +In Cassandra 4.2 and onwards, dependencies are managed in Maven POM templates +in `.build/*-template.xml`. These templates are processed into valid Maven POMs +with the `ant write-poms` task and copied to `build/*.pom`. + +The following POMs from `build.xml` have been migrated to templates: +* `parent-pom` is now at `.build/parent-pom-template.xml` +* `all-pom` is now at `.build/cassandra-deps-template.xml` +* `build-deps-pom` is now at `.build/cassandra-build-deps-template.xml` + +To add new dependencies in Cassandra 4.2 onwards, add the dependency to +`parent-pom-template` and `cassandra-deps-template`, and optionally +`cassandra-build-deps-template` if the dependency is required for build only. +See +https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Management[the +Maven docs] on how to reference dependencies in the parent POM from the child +POMs. + +For dependency versions that need to be available in `build.xml` and +`parent-pom-template`, specify the version as a property in `build.xml`, add it +to the `ant write-poms` target, then add the property to `parent-pom-template` +with the value of the template substitution. + +For more information on this change, see +https://issues.apache.org/jira/browse/CASSANDRA-17750[CASSANDRA-17750]. Review Comment: I think that the process needs to be spelled out because the people reading this will not be the developer that has experience with it. It needs to be clear in a fairly step by step process. Linking to external documentation is advantageous and while I think we can expect that developers know how to specify a Maven dependency, the link to the Maven documentation should be included. ########## site-content/source/modules/ROOT/pages/development/dependencies.adoc: ########## @@ -2,20 +2,45 @@ == Dependency Management -Managing libraries for Cassandra is a bit less straight forward compared -to other projects, as the build process is based on ant, maven and -manually managed jars. Make sure to follow the steps below carefully and -pay attention to any emerging issues in the `ci` and reported related -issues on Jira/ML, in case of any project dependency changes. +New dependencies should not be included without community consensus first being +obtained via a `[DISCUSS]` thread on the [email protected] mailing list. As Cassandra is an Apache product, all included libraries must follow Apache's https://www.apache.org/legal/resolved.html[software license requirements]. -=== Required steps to add or update libraries +=== Dependency management in Cassandra 4.2 and onwards + +In Cassandra 4.2 and onwards, dependencies are managed in Maven POM templates +in `.build/*-template.xml`. These templates are processed into valid Maven POMs +with the `ant write-poms` task and copied to `build/*.pom`. Review Comment: This block does not seem to render correctly in the github viewer. That may be an artifact of the viewer. However the `*` symbols are swallowed in the View File -> Preview mode. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
