Claudenw commented on code in PR #170: URL: https://github.com/apache/cassandra-website/pull/170#discussion_r1379682759
########## site-content/source/modules/ROOT/pages/development/dependencies.adoc: ########## @@ -2,50 +2,83 @@ == 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 - -* Add or replace jar file in `lib` directory -* Add or update `lib/license` files -* Update dependencies in `build.xml` -** Add to `parent-pom` with correct version -** Add to `all-pom` if simple Cassandra dependency (see below) - -=== POM file types - -* *parent-pom* - contains all dependencies with the respective version. -All other poms will refer to the artifacts with specified versions -listed here. -* *build-deps-pom(-sources)* + *coverage-deps-pom* - used by `ant build` -compile target. Listed dependenices will be resolved and copied to -`build/lib/{jar,sources}` by executing the -`maven-ant-tasks-retrieve-build` target. This should contain libraries -that are required for build tools (grammar, docs, instrumentation), but -are not shipped as part of the Cassandra distribution. -* *test-deps-pom* - refered by `maven-ant-tasks-retrieve-test` to -retrieve and save dependencies to `build/test/lib`. Exclusively used -during JUnit test execution. -* *all-pom* - pom for -https://mvnrepository.com/artifact/org.apache.cassandra/cassandra-all[cassandra-all.jar] -that can be installed or deployed to public maven repos via -`ant publish` +Cassandra uses the Ant build system and Maven POMs for dependency specification. +In Cassandra 4.2 the format of POMs was moved from within the `build.xml` file to separate POM template files that are processed by Ant. +In both pre-4.2 and post-4.2 Cassandra, there are several POMs that dependencies can be included in: + +* *parent-pom* + - Contains all dependencies with the respective version. All other poms + will refer to the artifacts with specified versions listed here. + - Since Cassandra 4.2, the `parent-pom` template is `.build/parent-pom-template.xml`. +* *build-deps-pom(-sources)* + *coverage-deps-pom* + - used by the `ant build` target. Listed dependencies will be resolved and + copied to `build/lib/{jar,sources}` by executing the + `maven-ant-tasks-retrieve-build` target. This should contain libraries that are + required for build tools (grammar, docs, instrumentation), but are not + shipped as part of the Cassandra distribution. + - Since Cassandra 4.0, `coverage-deps-pom` has been removed and the + `build-deps-pom` template is `.build/cassandra-build-deps-template.xml`. +* *all-pom* + - POM for https://mvnrepository.com/artifact/org.apache.cassandra/cassandra-all[cassandra-all.jar] + that can be installed or deployed to public maven repos via `ant publish`. + - Since Cassandra 4.2, the `all-pom` template is `.build/cassandra-deps-template.xml`. +* *test-deps-pom* + - Referenced by `maven-ant-tasks-retrieve-test` to retrieve and save + dependencies to `build/test/lib`. Exclusively used during JUnit test + execution. + - Since Cassandra 3.0, `test-deps-pom` has been removed. + +The `ant write-poms` target produces valid POM files in the `build/` directory. + +=== Dependency management before Cassandra 4.2 + +To update dependencies, update the parent and child POM definitions in +`build.xml`. The parent POM should include the `dependency` tag with `groupId`, +`artifactId`, `version`, and optional `scope` fields. The child POM(s) should +include the `dependency` tag with `groupId` and `artifactId`. See the +https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Management[Maven docs] +for a complete reference on how to reference dependencies across parent and +child POMs. + +Here is +https://github.com/apache/cassandra/commit/4b3f07fc74089151efeff7a8fdfa9c414a1f0d6a#diff-766797f233c18114f9499750cf1ffbf3829aeea50283850619c01bd173132021[an example] +of a commit that changes dependency versions pre-4.2. + +=== Dependency management in Cassandra 4.2 and later + +In Cassandra 4.2 and later, dependencies are managed in Maven POM templates in +`.build/\*-template.xml`. These templates are processed into valid Maven POMs +and copied to `build/\*.pom` by the `ant write-poms` task. Review Comment: This is weird but the `.build/\*-template.xml` displays correctly on my system while the `build/\*.pom` does not. In my editor they both display correctly. Is there a way to see how the publishing system will render them? -- 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]
