sergehuber commented on code in PR #736: URL: https://github.com/apache/unomi/pull/736#discussion_r2564879001
########## 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: Review Comment: Done ########## 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 not ? Anyway I rephrased it following your suggestion. ########## 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: Fix that by rephrasing. -- 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]
