jayblanc commented on code in PR #736: URL: https://github.com/apache/unomi/pull/736#discussion_r2549008778
########## 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: I would have put the 'more info' section at the end -- 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]
