jayblanc commented on code in PR #736: URL: https://github.com/apache/unomi/pull/736#discussion_r2549016491
########## manual/src/main/asciidoc/building-and-deploying.adoc: ########## @@ -64,6 +64,111 @@ TIP: On a non-English Windows env, the Asciidoctor Maven Plugin may fail to + . The distributions will be available under "package/target" directory. +==== Updating the website + +Use the top-level `generate-manual.sh` script to generate and publish the documentation website. + +[source] +---- +./generate-manual.sh publish <svn_user> <svn_pass> +./generate-manual.sh simulate <svn_user> <svn_pass> +---- + +Modes: + +* `publish`: generates all documentation and publishes to Apache SVN +** Generates exactly 2 versions (latest + stable) +** Publishes HTML manual to `$SVN_WEBSITE_BASE/manual` and API docs from master +** Uploads release packages (PDF/ZIP) to Apache Dist SVN for non-master branches +** Removes old versions automatically on the website + +* `simulate`: dry-run; prints the commands without making changes + +Requirements: + +* Java 11+, Maven 3.6+, Git, SVN client, `bc` +* Access to the `master` and the stable branch configured in `generate-manual-config.sh` + +Outputs and locations: + +* Staging directories under `target/generated-docs/` (created by the build) +* Website content committed to `$SVN_WEBSITE_BASE/manual/<version>` +* Release artifacts (PDF/ZIP + signatures/checksums) committed to Apache Dist SVN at `$SVN_DIST_BASE/<version>` + +Notes: + +* The script sources optional `generate-manual-config.sh` and `shell-utils.sh` for configuration/utilities. +* Javadoc aggregation is attempted; if it fails (toolchain mismatch), the rest still publishes. + +==== JGitFlow + +You can use the https://jgitflow.bitbucket.org[JGitFlow Maven plugin] to work with feature, hotfix and other types of branches. + +For example, to start a feature branch, simply use: + +[source] +---- +mvn jgitflow:feature-start +---- + +This will prompt you for the feature name, and then create a feature branch and update all the POMs to have a version that contains the feature name. This makes it easier to integrate with continuous integration systems to generate builds for the feature branch. + +Once the feature is completed you can use: + +[source] +---- +mvn jgitflow:feature-finish +---- + +To merge the branch into master. + +==== Maven Build Cache + +Apache Unomi uses the Maven Build Cache extension to significantly improve build performance by caching compiled artifacts and avoiding unnecessary recompilation. + +For more information, see the official documentation: + +* https://maven.apache.org/extensions/maven-build-cache-extension/[Maven Build Cache Extension Overview] +* https://maven.apache.org/extensions/maven-build-cache-extension/parameters.html[Build Cache Parameters Reference] + +Performance improvements: + +* Without cache: ~1 minute 59 seconds for a full clean install Review Comment: Why do we have performance improvement metrics section in the documentation ? Maybe a simple rewrite of the previous sentence (Apache unomi...) would be enough like: Apache Unomi uses the Maven Build Cache extension to significantly improve build efficiency by caching compiled artifacts and avoiding unnecessary recompilation (build time without/with cached artifacts ~2mn/~3s) ########## manual/src/main/asciidoc/building-and-deploying.adoc: ########## @@ -64,6 +64,111 @@ TIP: On a non-English Windows env, the Asciidoctor Maven Plugin may fail to + . The distributions will be available under "package/target" directory. +==== Updating the website + +Use the top-level `generate-manual.sh` script to generate and publish the documentation website. + +[source] +---- +./generate-manual.sh publish <svn_user> <svn_pass> +./generate-manual.sh simulate <svn_user> <svn_pass> +---- + +Modes: + +* `publish`: generates all documentation and publishes to Apache SVN +** Generates exactly 2 versions (latest + stable) +** Publishes HTML manual to `$SVN_WEBSITE_BASE/manual` and API docs from master +** Uploads release packages (PDF/ZIP) to Apache Dist SVN for non-master branches +** Removes old versions automatically on the website + +* `simulate`: dry-run; prints the commands without making changes + +Requirements: + +* Java 11+, Maven 3.6+, Git, SVN client, `bc` Review Comment: I think it's Java 17 now. Even if that goal is able to complete using Java11, as the whole project is now based on Java 17 maybe it's better to upgrade that part too. ########## .mvn/maven-build-cache-config.xml: ########## @@ -0,0 +1,59 @@ +<!-- - + 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. + --> +<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 https://maven.apache.org/xsd/build-cache-config-1.0.0.xsd";> + <!-- + Template Maven build cache configuration + --> + <configuration> + <enabled>true</enabled> + <hashAlgorithm>SHA-256</hashAlgorithm> + <validateXml>true</validateXml> + <remote enabled="false"> + <url>http://host:port</url> + </remote> + <local> + <maxBuildsCached>3</maxBuildsCached> + </local> + <projectVersioning adjustMetaInf="true" /> + </configuration> + <input> + <global> + <!-- If not defined, default glob is "*" --> Review Comment: All those comments are from the template config file, I think we can remove all of them. ########## .mvn/maven-build-cache-config.xml: ########## @@ -0,0 +1,59 @@ +<!-- - + 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. + --> +<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 https://maven.apache.org/xsd/build-cache-config-1.0.0.xsd";> + <!-- + Template Maven build cache configuration + --> + <configuration> Review Comment: Do we still keep those type of comments ? ########## .mvn/extensions.xml: ########## @@ -0,0 +1,23 @@ +<!-- - + 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. + --> +<extensions> + <extension> + <groupId>org.apache.maven.extensions</groupId> + <artifactId>maven-build-cache-extension</artifactId> + <version>1.2.0</version> Review Comment: There is a newer version 1.2.1 ########## manual/src/main/asciidoc/building-and-deploying.adoc: ########## @@ -64,6 +64,111 @@ TIP: On a non-English Windows env, the Asciidoctor Maven Plugin may fail to + . The distributions will be available under "package/target" directory. +==== Updating the website + +Use the top-level `generate-manual.sh` script to generate and publish the documentation website. + +[source] +---- +./generate-manual.sh publish <svn_user> <svn_pass> +./generate-manual.sh simulate <svn_user> <svn_pass> +---- + +Modes: + +* `publish`: generates all documentation and publishes to Apache SVN +** Generates exactly 2 versions (latest + stable) +** Publishes HTML manual to `$SVN_WEBSITE_BASE/manual` and API docs from master +** Uploads release packages (PDF/ZIP) to Apache Dist SVN for non-master branches +** Removes old versions automatically on the website + +* `simulate`: dry-run; prints the commands without making changes + +Requirements: + +* Java 11+, Maven 3.6+, Git, SVN client, `bc` +* Access to the `master` and the stable branch configured in `generate-manual-config.sh` + +Outputs and locations: + +* Staging directories under `target/generated-docs/` (created by the build) +* Website content committed to `$SVN_WEBSITE_BASE/manual/<version>` +* Release artifacts (PDF/ZIP + signatures/checksums) committed to Apache Dist SVN at `$SVN_DIST_BASE/<version>` + +Notes: + +* The script sources optional `generate-manual-config.sh` and `shell-utils.sh` for configuration/utilities. +* Javadoc aggregation is attempted; if it fails (toolchain mismatch), the rest still publishes. + +==== JGitFlow + +You can use the https://jgitflow.bitbucket.org[JGitFlow Maven plugin] to work with feature, hotfix and other types of branches. + +For example, to start a feature branch, simply use: + +[source] +---- +mvn jgitflow:feature-start +---- + +This will prompt you for the feature name, and then create a feature branch and update all the POMs to have a version that contains the feature name. This makes it easier to integrate with continuous integration systems to generate builds for the feature branch. + +Once the feature is completed you can use: + +[source] +---- +mvn jgitflow:feature-finish +---- + +To merge the branch into master. + +==== Maven Build Cache + +Apache Unomi uses the Maven Build Cache extension to significantly improve build performance by caching compiled artifacts and avoiding unnecessary recompilation. + +For more information, see the official documentation: + +* https://maven.apache.org/extensions/maven-build-cache-extension/[Maven Build Cache Extension Overview] +* https://maven.apache.org/extensions/maven-build-cache-extension/parameters.html[Build Cache Parameters Reference] + +Performance improvements: + +* Without cache: ~1 minute 59 seconds for a full clean install +* With cache: ~3.176 seconds for subsequent builds (after initial build) + +The build cache is enabled by default and configured in the `.mvn/maven-build-cache-config.xml` file. The cache configuration includes: + +* Local caching with up to 3 builds cached +* SHA-256 hash algorithm for cache keys +* Includes all source directories (`src/`) +* Excludes `pom.xml` files and generated sources (`src/main/javagen/**`) + +Command line control: + +* Disable cache: `mvn -Dmaven.build.cache.enabled=false clean install` + ** Completely turns off the build cache functionality + ** Maven will not store or retrieve any build outputs from the cache + ** Performs a full build as if the cache were not present + ** Use this when you want to ensure no cache influence on the build + +* Skip cache (force rebuild): `mvn -Dmaven.build.cache.skipCache=true clean install` + ** Skips looking up artifacts in caches but still writes new results to cache + ** Forces Maven to rebuild everything without using cached artifacts + ** New build results will be stored in cache for future builds + ** Use this to force a complete rebuild while keeping cache functionality active + +* Enable cache (default): `mvn -Dmaven.build.cache.enabled=true clean install` + ** Enables full cache functionality (read and write) + ** Maven will use cached artifacts when available and store new results + ** This is the default behavior when the cache is enabled + +Purging the build cache: + +To completely reset the build cache and force a full rebuild: + Review Comment: The command is the same than before. I would have removed that line (Skip cache..) and moved the next line (Or manually) to the previous section (purging). ########## manual/src/main/asciidoc/building-and-deploying.adoc: ########## @@ -64,6 +64,111 @@ TIP: On a non-English Windows env, the Asciidoctor Maven Plugin may fail to + . The distributions will be available under "package/target" directory. +==== Updating the website + +Use the top-level `generate-manual.sh` script to generate and publish the documentation website. + +[source] +---- +./generate-manual.sh publish <svn_user> <svn_pass> +./generate-manual.sh simulate <svn_user> <svn_pass> +---- + +Modes: + +* `publish`: generates all documentation and publishes to Apache SVN +** Generates exactly 2 versions (latest + stable) +** Publishes HTML manual to `$SVN_WEBSITE_BASE/manual` and API docs from master +** Uploads release packages (PDF/ZIP) to Apache Dist SVN for non-master branches +** Removes old versions automatically on the website + +* `simulate`: dry-run; prints the commands without making changes + +Requirements: + +* Java 11+, Maven 3.6+, Git, SVN client, `bc` +* Access to the `master` and the stable branch configured in `generate-manual-config.sh` + +Outputs and locations: + +* Staging directories under `target/generated-docs/` (created by the build) +* Website content committed to `$SVN_WEBSITE_BASE/manual/<version>` +* Release artifacts (PDF/ZIP + signatures/checksums) committed to Apache Dist SVN at `$SVN_DIST_BASE/<version>` + +Notes: + +* The script sources optional `generate-manual-config.sh` and `shell-utils.sh` for configuration/utilities. +* Javadoc aggregation is attempted; if it fails (toolchain mismatch), the rest still publishes. + +==== JGitFlow + +You can use the https://jgitflow.bitbucket.org[JGitFlow Maven plugin] to work with feature, hotfix and other types of branches. + +For example, to start a feature branch, simply use: + +[source] +---- +mvn jgitflow:feature-start +---- + +This will prompt you for the feature name, and then create a feature branch and update all the POMs to have a version that contains the feature name. This makes it easier to integrate with continuous integration systems to generate builds for the feature branch. + +Once the feature is completed you can use: + +[source] +---- +mvn jgitflow:feature-finish +---- + +To merge the branch into master. + +==== Maven Build Cache + +Apache Unomi uses the Maven Build Cache extension to significantly improve build performance by caching compiled artifacts and avoiding unnecessary recompilation. + +For more information, see the official documentation: + +* https://maven.apache.org/extensions/maven-build-cache-extension/[Maven Build Cache Extension Overview] +* https://maven.apache.org/extensions/maven-build-cache-extension/parameters.html[Build Cache Parameters Reference] + +Performance improvements: + +* Without cache: ~1 minute 59 seconds for a full clean install +* With cache: ~3.176 seconds for subsequent builds (after initial build) + +The build cache is enabled by default and configured in the `.mvn/maven-build-cache-config.xml` file. The cache configuration includes: + +* Local caching with up to 3 builds cached +* SHA-256 hash algorithm for cache keys +* Includes all source directories (`src/`) +* Excludes `pom.xml` files and generated sources (`src/main/javagen/**`) + +Command line control: + +* Disable cache: `mvn -Dmaven.build.cache.enabled=false clean install` + ** Completely turns off the build cache functionality + ** Maven will not store or retrieve any build outputs from the cache + ** Performs a full build as if the cache were not present + ** Use this when you want to ensure no cache influence on the build + +* Skip cache (force rebuild): `mvn -Dmaven.build.cache.skipCache=true clean install` + ** Skips looking up artifacts in caches but still writes new results to cache + ** Forces Maven to rebuild everything without using cached artifacts + ** New build results will be stored in cache for future builds + ** Use this to force a complete rebuild while keeping cache functionality active + +* Enable cache (default): `mvn -Dmaven.build.cache.enabled=true clean install` + ** Enables full cache functionality (read and write) + ** Maven will use cached artifacts when available and store new results + ** This is the default behavior when the cache is enabled + +Purging the build cache: + Review Comment: There is nothing in Purging the build cache section... -- 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]
