This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch release-2.0.0-M7-RC1 in repository https://gitbox.apache.org/repos/asf/isis.git
commit ead00bba1068194e82fad706c5a1fd64aca4c457 Author: Dan Haywood <[email protected]> AuthorDate: Sun Feb 13 13:22:39 2022 +0000 ISIS-2859: update docs release process. --- .../modules/ROOT/pages/cutting-a-release.adoc | 199 ++++++++++++++------- .../ROOT/pages/post-release-successful.adoc | 17 +- .../modules/ROOT/pages/updating-the-website.adoc | 28 ++- .../ROOT/partials/publish-and-index-website.adoc | 2 +- .../pages/building-docs-and-website.adoc | 43 ++++- 5 files changed, 211 insertions(+), 78 deletions(-) diff --git a/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc b/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc index f96363c..23de7d7 100644 --- a/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc +++ b/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc @@ -157,22 +157,29 @@ Locate this property in `isis-parent/pom.xml` and update to the current date/tim The next step is to generate the website, ensuring that the config, examples, projdoc (system overview and global index) are all updated. -Be careful that sometimes the configuration property pages (that are generated from the `core/config/target/classes/META-INF/spring-configuration-metadata.json` file) may be malformed; in particular for default values going missing. - +* Be careful that sometimes the configuration property pages (that are generated from the `core/config/target/classes/META-INF/spring-configuration-metadata.json` file) may be malformed; in particular for default values going missing. ++ This seems to occur if the IDE (IntelliJ) has compiled the codebase. - ++ The workaround is to rebuild the `core/config` Maven module using `mvn` command line first. - ++ [source,bash,subs="attributes+"] ---- mvn clean install -pl core/config ---- -Then, generate the website: +* It's also necessary to make sure the tooling is built: ++ +[source,bash,subs="attributes+"] +---- +mvn -D module-tooling -D skip.essential install -DskipTests +---- +* Then, generate the website: ++ [source,bash,subs="attributes+"] ---- -sh preview.sh +bash preview.sh ---- Check for any Asciidoc errors, and fix. @@ -484,143 +491,191 @@ The general idea is that a release will fast-forward `jdo` to `jdo-SNAPSHOT` and In order that we don't break the starter apps while a release is being voted on, we do the changes in work branches, `$ISISBRANCH-jdo` and `$ISISBRANCH-jpa`: -* for _helloworld_, we create a release branch for both variants: +=== HelloWorld + +For _helloworld_, we create a release branch for both variants: -** for `jdo`: +* for `jpa`: ++ +** Checkout the branch, bump versions, and commit: + [source,bash,subs="attributes+"] ---- -git checkout jdo-SNAPSHOT +git checkout jpa-SNAPSHOT git pull --ff-only -git checkout -b $ISISBRANCH-jdo +git checkout -b $ISISBRANCH-jpa mvn versions:update-parent -DparentVersion=$ISISREL # <.> mvn versions:set -DnewVersion=$ISISREL -mvn clean install -o -mvn spring-boot:run +git add . +git commit -m "$ISISJIRA - updates to $ISISREL (jpa)" ---- + <.> the top-level `pom.xml` references the ASF staging repository, so this will pull down the release if not already present in `~/.m2/repository`. + +** Test the app + -Commit any changes and then push the branch to origin: +[source,bash,subs="attributes+"] +---- +mvn clean install -o +mvn spring-boot:run +---- + +** Make any additional changes that might be required (eg update to `menubars.layout.xml`) commit and retest + +** Push the branch to origin: + [source,bash,subs="attributes+"] ---- -git add . -git commit -m "$ISISJIRA - updates to $ISISREL (jdo)" -git push -u origin $ISISBRANCH-jdo +git push -u origin $ISISBRANCH-jpa ---- -** repeat for `jpa`: +* for `jdo`: ++ +** Checkout the branch, bump versions, and commit: + [source,bash,subs="attributes+"] ---- -git checkout jpa-SNAPSHOT +git checkout jdo-SNAPSHOT git pull --ff-only -git checkout -b $ISISBRANCH-jpa +git checkout -b $ISISBRANCH-jdo mvn versions:update-parent -DparentVersion=$ISISREL mvn versions:set -DnewVersion=$ISISREL +git add . +git commit -m "$ISISJIRA - updates to $ISISREL (jdo)" +---- + +** Test the app ++ +[source,bash,subs="attributes+"] +---- mvn clean install -o mvn spring-boot:run ---- + +** Make any additional changes that might be required, and re-test. + -Commit any changes and then push the branch to origin: +This might be easiest to just cherry-pick commits made on the `jpa` branch. + +** Merge in the `jpa` branch, discarding any conflicts. + [source,bash,subs="attributes+"] ---- -git add . -git commit -m "$ISISJIRA - updates to $ISISREL (jpa)" -git push -u origin $ISISBRANCH-jpa +git merge $ISISBRANCH-jpa --no-commit +---- ++ +The idea here is to show equivalence between the two branches. +The merge commit should end up with no changes: ++ +[source,bash,subs="attributes+"] +---- +git commit -m "$ISISJIRA - merge in jpa" ---- -* for _simple app_, the steps are almost the same: - -** for `jdo`: +** Push the branch to origin: + --- +[source,bash,subs="attributes+"] +---- +git push -u origin $ISISBRANCH-jdo +---- +=== SimpleApp + +For _simple app_, the steps are almost the same: + +* for `jpa`: + +** Checkout the branch, bump versions, and commit: ++ [source,bash,subs="attributes+"] ---- -git checkout jdo-SNAPSHOT +git checkout jpa-SNAPSHOT git pull --ff-only -git checkout -b $ISISBRANCH-jdo +git checkout -b $ISISBRANCH-jpa -mvn versions:update-parent -DparentVersion=$ISISREL # <.> +mvn versions:update-parent -DparentVersion=$ISISREL # <.> mvn versions:set -DnewVersion=$ISISREL -mvn clean install -Dmetamodel.lockdown -B -o # <.> +git add . +git commit -m "$ISISJIRA - updates to $ISISREL (jpa)" ---- - <.> the top-level `pom.xml` references the ASF staging repository, so this will pull down the release if not already present in `~/.m2/repository`. -<.> the -B flag is required to avoid control characters in generated output - -Approve any failed lockdown tests (the mavendeps will fail first time around because the dependencies on Apache Isis itself have just be bumped). - -You could also check the output of the Cucumber tests, under: - -*** `webapp-tests/target/cucumber-reports` and -*** `webapp-tests/target/cucumber-html-reports`. - - -Repeat, then run the app as a sanity check: +** Test the app ++ [source,bash,subs="attributes+"] ---- +mvn clean install -o mvn -pl webapp spring-boot:run ---- -Commit any changes and then push the branch to origin: +** Make any additional changes that might be required (eg update to `menubars.layout.xml`) commit and retest +** Push the branch to origin: ++ [source,bash,subs="attributes+"] ---- -git add . -git commit -m "$ISISJIRA - updates to $ISISREL (jdo)" -git push -u origin $ISISBRANCH-jdo +git push -u origin $ISISBRANCH-jpa ---- --- -** repeat for `jpa`: -+ --- +* for `jdo`: ++ +** Checkout the branch, bump versions, and commit: ++ [source,bash,subs="attributes+"] ---- -git checkout jpa-SNAPSHOT +git checkout jdo-SNAPSHOT git pull --ff-only -git checkout -b $ISISBRANCH-jpa +git checkout -b $ISISBRANCH-jdo mvn versions:update-parent -DparentVersion=$ISISREL mvn versions:set -DnewVersion=$ISISREL -mvn clean install -Dmetamodel.lockdown -B -o +git add . +git commit -m "$ISISJIRA - updates to $ISISREL (jdo)" ---- -Approve any failed lockdown tests (the mavendeps will fail first time around because the dependencies on Apache Isis itself have just be bumped). - -Repeat, then run the app as a sanity check: - +** Test the app ++ [source,bash,subs="attributes+"] ---- +mvn clean install -o mvn -pl webapp spring-boot:run ---- -Commit any changes and then push the branch to origin: +** Make any additional changes that might be required, and re-test. ++ +This might be easiest to just cherry-pick commits made on the `jpa` branch. +** Merge in the `jpa` branch, discarding any conflicts. ++ [source,bash,subs="attributes+"] ---- -git add . -git commit -m "$ISISJIRA - updates to $ISISREL (jpa)" -git push -u origin $ISISBRANCH-jpa +git merge $ISISBRANCH-jpa --no-commit +---- ++ +The idea here is to show equivalence between the two branches. +The merge commit should end up with no changes: ++ +[source,bash,subs="attributes+"] +---- +git commit -m "$ISISJIRA - merge in jpa" ---- --- +** Push the branch to origin: ++ +[source,bash,subs="attributes+"] +---- +git push -u origin $ISISBRANCH-jdo +---- == Preview website @@ -664,14 +719,26 @@ popd ---- cd ../isis-release -sh preview.sh -A +bash preview.sh -A ---- + [WARNING] ==== This procedure doesn't yet work; Antora does not yet support worktrees. -So instead it's currently necessary to perform the preview in the main `../isis` directory (switch branches first, of course). +So instead it's currently necessary to perform the preview in the main `../isis` directory, switching branches. +You'll also need to rebuild all and then regenerate config files and tooling: + +[source,bash,subs="attributes+"] +---- +git checkout $ISISBRANCH +pushd isis-parent +mvn clean install -DskipTests -Dreleased +popd +mvn clean install -pl core/config +mvn -D module-tooling -D skip.essential install -DskipTests +---- + ==== @@ -691,7 +758,7 @@ cd ../isis-site git add . git commit -m "$ISISJIRA : staging changes to website" -sh preview.sh +bash preview.sh ---- * If happy, then push the changes: diff --git a/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc b/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc index 085a0b8..502f0e4 100644 --- a/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc +++ b/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc @@ -367,13 +367,26 @@ git add . git commit -m "$ISISJIRA: updates references to version in index.html and site.yml" ---- -We are now in a position to actually generate the Antora website: +We are now in a position to actually generate the Antora website. +(NOTE, this needs to be performed in the `../isis` directory because Antora currently doesn't support git worktrees) + +* build prereqs ++ +[source,bash,subs="attributes+"] +---- +git checkout $ISISBRANCH +pushd isis-parent +mvn clean install -DskipTests -Dreleased +popd +mvn clean install -pl core/config +mvn -D module-tooling -D skip.essential install -DskipTests +---- * generate the website: + [source,bash,subs="attributes+"] ---- -sh preview.sh +bash preview.sh ---- + This will write to `antora/target/site`; we'll use the results in the xref:#publish-website[next section]. diff --git a/antora/components/comguide/modules/ROOT/pages/updating-the-website.adoc b/antora/components/comguide/modules/ROOT/pages/updating-the-website.adoc index 63748b0..4136791 100644 --- a/antora/components/comguide/modules/ROOT/pages/updating-the-website.adoc +++ b/antora/components/comguide/modules/ROOT/pages/updating-the-website.adoc @@ -20,11 +20,37 @@ git checkout {page-isisrel} * make documentation updates, and commit changes +* make sure config properties are up-to-date: ++ +This is most easily done by rebuilding all: ++ +[source,bash,subs="attributes+"] +---- +pushd isis-parent +mvn clean install -DskipTests -Dreleased +popd +---- ++ +Though it might be sufficient to just build the core/config module ++ +[source,bash,subs="attributes+"] +---- +mvn clean install -pl core/config +---- + + +* make sure the tooling is also built: ++ +[source,bash,subs="attributes+"] +---- +mvn -D module-tooling -D skip.essential install -DskipTests +---- + * generate the website: + [source,bash,subs="attributes+"] ---- -sh preview.sh +bash preview.sh ---- + This will write to `antora/target/site`; we'll use the results in the xref:#publish-website[next section]. diff --git a/antora/components/comguide/modules/ROOT/partials/publish-and-index-website.adoc b/antora/components/comguide/modules/ROOT/partials/publish-and-index-website.adoc index 80dee33..5dfa179 100644 --- a/antora/components/comguide/modules/ROOT/partials/publish-and-index-website.adoc +++ b/antora/components/comguide/modules/ROOT/partials/publish-and-index-website.adoc @@ -45,7 +45,7 @@ git add . ---- git commit -m "updates website" -sh preview.sh +bash preview.sh ---- * If everything looks ok, then push the changes to make live, and switch back to the `isis` repo: diff --git a/antora/components/conguide/modules/documentation/pages/building-docs-and-website.adoc b/antora/components/conguide/modules/documentation/pages/building-docs-and-website.adoc index 98252ef..994e77d 100644 --- a/antora/components/conguide/modules/documentation/pages/building-docs-and-website.adoc +++ b/antora/components/conguide/modules/documentation/pages/building-docs-and-website.adoc @@ -9,27 +9,54 @@ The Apache Isis website and documentation are written in link:https://asciidocto The prerequisites to install are: * Node LTS (link:https://nodejs.org/[]) -* Antora (comprising: link:https://www.npmjs.com/package/@antora/cli[@antora/cli] and link:https://www.npmjs.com/package/@antora/site-generator-default[@antora/site-generator-default]) - -* Asciidoctor Kroki (link:https://www.npmjs.com/package/asciidoctor-kroki[asciidoctor-kroki]) + -for diagramming support for Antora - -Assuming you have installed the latest Node LTS, these can be installed using: - [source,bash] ---- -npm i -g @antora/cli @antora/site-generator-default asciidoctor-kroki +sudo apt install nodejs +sudo apt install npm ---- +* Antora (link:https://www.npmjs.com/package/@antora/cli[@antora/cli] & link:https://www.npmjs.com/package/@antora/site-generator-default[@antora/site-generator-default]), and Kroki (link:https://www.npmjs.com/package/asciidoctor-kroki[asciidoctor-kroki]) for diagramming support: ++ +[source,bash] +---- +npm i -g @antora/[email protected] @antora/[email protected] [email protected] +---- ++ See the link:https://docs.antora.org/antora/2.3/install/install-antora/[Antora docs] for details. +* Serve (link:https://www.npmjs.com/package/serve[serve]) for previewing: ++ +[source,bash] +---- +npm i -g [email protected] +---- + We also generate some Asciidoc files dynamically from other source code. This requires: * link:https://groovy.apache.org/download.html[Groovy 2.x] ++ +eg, using link:https://sdkman.io/install[sdkman]: ++ +[source,bash] +---- +sdk install groovy 2.5.15 +---- * link:https://pandoc.org/installing.html[pandoc] ++ +[source,bash] +---- +sudo apt install pandoc +---- + +* dos2unix ++ +[source,bash] +---- +sudo apt install dos2unix +---- == Authoring
