ARTEMIS-4533: update CI build, update READMEs/docs to reference examp…

…les repo and refresh queue example output, tweak assembly as needed, update release steps
apache · Dec 14, 2023 · 547aa2f · 547aa2f
1 parent 2564078
commit 547aa2f
Show file tree

Hide file tree

Showing 9 changed files with 147 additions and 452 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -1,6 +1,25 @@
 name: "Build"
 
-on: [push, pull_request, workflow_dispatch]
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      examplesRepoUserOrOrg:
+        description: 'The examples repo to use'
+        required: true
+        default: 'apache/activemq-artemis-examples'
+        type: string
+      examplesRepoBranch:
+        description: 'Branch in examples repo'
+        required: true
+        default: 'development'
+        type: string
+
+env:
+  EXAMPLES_REPO: ${{ inputs.examplesRepoUserOrOrg || 'apache/activemq-artemis-examples' }}
+  EXAMPLES_BRANCH: ${{ inputs.examplesRepoBranch || 'development' }}
+
 
 jobs:
   test:
@@ -13,14 +32,16 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
+        with:
+          path: activemq-artemis
 
       - name: Cache Maven Local Repo
         if: ${{ !startsWith(github.ref, 'refs/tags/') }}
         uses: actions/cache@v3
         with:
           path: |
             ~/.m2/repository/
-          key: ${{ runner.os }}-mvn-${{ hashFiles('**/pom.xml') }}
+          key: ${{ runner.os }}-mvn-${{ hashFiles('activemq-artemis/**/pom.xml') }}
           restore-keys: |
             ${{ runner.os }}-mvn-
 
@@ -34,6 +55,7 @@ jobs:
       # By setting anything to org.apache.activemq.artemis.core.io.aio.AIOSequentialFileFactory.DISABLED we are disabling libaio loading on the testsuite
       - name: Fast Tests
         run: |
+          cd activemq-artemis
           mvn -s .github/maven-settings.xml -Dorg.apache.activemq.artemis.core.io.aio.AIOSequentialFileFactory.DISABLED=AnythingNotNull -Pfast-tests -Pcompatibility-tests install
 
       - name: Clean Up Before Caching
@@ -52,14 +74,16 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
+        with:
+          path: activemq-artemis
 
       - name: Cache Maven Local Repo
         if: ${{ !startsWith(github.ref, 'refs/tags/') }}
         uses: actions/cache@v3
         with:
           path: |
             ~/.m2/repository/
-          key: ${{ runner.os }}-mvn-${{ hashFiles('**/pom.xml') }}
+          key: ${{ runner.os }}-mvn-${{ hashFiles('activemq-artemis/**/pom.xml') }}
           restore-keys: |
             ${{ runner.os }}-mvn-
 
@@ -69,35 +93,54 @@ jobs:
           java-version: ${{ matrix.java }}
           distribution: 'temurin'
 
+      - name: Checkout Artemis Examples Repo
+        uses: actions/checkout@v3
+        with:
+          repository: ${{ env.EXAMPLES_REPO }}
+          ref: ${{ env.EXAMPLES_BRANCH }}
+          path: activemq-artemis-examples
+
       - name: Build Main
         run: |
+          cd activemq-artemis
           mvn -s .github/maven-settings.xml -DskipTests -Derrorprone -Pdev -Pjmh install
 
+      - name: Set Examples Version to Artemis Version
+        run: |
+          cd activemq-artemis
+          CURRENT_ARTEMIS_BUILD_VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)
+          echo "Current Artemis version: ${CURRENT_ARTEMIS_BUILD_VERSION}"
+          cd ../activemq-artemis-examples
+          ./scripts/update-examples-version.sh ${CURRENT_ARTEMIS_BUILD_VERSION}
+
       - name: Build Examples (JDK11 / -Prelease)
         if: matrix.java == '11'
         run: |
-          cd examples
-          mvn -s ../.github/maven-settings.xml install -Prelease
+          cd activemq-artemis-examples
+          mvn -s ../activemq-artemis/.github/maven-settings.xml install -Prelease
 
       - name: Build Examples (JDK >11 / -Pexamples,noRun)
         if: matrix.java != '11'
         run: |
-          cd examples
-          mvn -s ../.github/maven-settings.xml install -Pexamples,noRun
+          cd activemq-artemis-examples
+          mvn -s ../activemq-artemis/.github/maven-settings.xml install -Pexamples,noRun
 
       - name: Javadoc Check (JDK11 / -Prelease)
         if: matrix.java == '11'
         run: |
+          cd activemq-artemis
           mvn -s .github/maven-settings.xml javadoc:javadoc -Prelease -DskipWebsiteDocGeneration=true -DskipWebsiteJavadocGeneration=true
 
       - name: Javadoc Check (JDK >11)
         if: matrix.java != '11'
         run: |
+          cd activemq-artemis
           mvn -s .github/maven-settings.xml javadoc:javadoc
 
       - name: Website Content Check (JDK11 only / -Prelease)
         if: matrix.java == '11'
         run: |
+          cd activemq-artemis
           mvn -s .github/maven-settings.xml clean install -DskipTests -Prelease -am -pl "artemis-website"
 
       - name: Clean Up Before Caching

diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ ActiveMQ Artemis is the next generation message broker from Apache ActiveMQ.
 
 See the [User Manual](https://activemq.apache.org/components/artemis/documentation/latest/) for an in-depth explanation of all aspects of broker configuration and behavior.
 
-The broker ships with many [examples](https://activemq.apache.org/components/artemis/documentation/latest/examples.html) which you can run, inspect, & modify.
+The [ActiveMQ Artemis Examples](https://github.com/apache/activemq-artemis-examples) repository contains over 90 examples demonstrating many of the client and broker features.
 
 ## How to Build, etc.
 

diff --git a/RELEASING.md b/RELEASING.md
@@ -322,6 +322,31 @@ Once the mirrors are up-to-date then update the following:
 Run `git add` for all the added directories & files and then `git commit -m "updates for <version> release"`.
 Once pushed, the changes should be published automatically by the `jekyll_websites` builder of the [apache buildbot](https://ci2.apache.org/#/builders).
 
+## Update Examples Repo
+
+The [examples repo](https://github.com/apache/activemq-artemis-examples) should be updated to reflect the new release and development versions.
+
+Take a fresh clone of the repo and run the provided script, then check the results and push.
+
+```
+git clone https://gitbox.apache.org/repos/asf/activemq-artemis-examples.git
+
+cd activemq-artemis-examples
+./scripts/release/update-branch-versions.sh <release-version> <new-main-snapshot-version>"
+```
+
+Example from the 2.32.0 release:
+```
+git clone https://gitbox.apache.org/repos/asf/activemq-artemis-examples.git
+
+cd activemq-artemis-examples
+./scripts/release/update-branch-versions.sh 2.32.0 2.33.0-SNAPSHOT"
+```
+
+Check things over and then push the `development` and `main` branches (optionally use your fork, to test things out before pushing to the main examples repo or even to raise PRs).
+
+NOTE: The `main` branch CI build does not build Artemis, so the release must be available on Maven Central before pushing main or the build will fail. The `development` branch will check out the Artemis main branch and build against that, or it can be manually triggered and pointed to e.g a release tag.
+
 ## Upload Docker Images
 
 1. If you don't have an account on https://hub.docker.com/ then create one.

diff --git a/artemis-distribution/pom.xml b/artemis-distribution/pom.xml
@@ -208,27 +208,6 @@
                </execution>
             </executions>
          </plugin>
-         <plugin>
-            <groupId>com.ruleoftech</groupId>
-            <artifactId>markdown-page-generator-plugin</artifactId>
-            <version>2.4.0</version>
-            <executions>
-               <execution>
-                  <phase>compile</phase>
-                  <goals>
-                     <goal>generate</goal>
-                  </goals>
-               </execution>
-            </executions>
-            <configuration>
-               <headerHtmlFile>${activemq.basedir}/examples/common/header.html</headerHtmlFile>
-               <footerHtmlFile>${activemq.basedir}/examples/common/footer.html</footerHtmlFile>
-               <inputDirectory>${activemq.basedir}/examples</inputDirectory>
-               <outputDirectory>${project.build.directory}/markdown-pages/examples</outputDirectory>
-               <recursiveInput>true</recursiveInput>
-               <pegdownExtensions>FENCED_CODE_BLOCKS</pegdownExtensions>
-            </configuration>
-         </plugin>
       </plugins>
    </build>
 

diff --git a/artemis-distribution/src/main/assembly/dep.xml b/artemis-distribution/src/main/assembly/dep.xml
@@ -151,41 +151,6 @@
          <directoryMode>0755</directoryMode>
          <fileMode>0755</fileMode>
       </fileSet>
-      <!-- examples -->
-      <fileSet>
-         <directory>${activemq.basedir}/examples</directory>
-         <outputDirectory>examples</outputDirectory>
-         <lineEnding>keep</lineEnding>
-         <excludes>
-            <exclude>**/target/**</exclude>
-            <exclude>**/**/*.iml</exclude>
-            <exclude>**/**/*.dat</exclude>
-            <exclude>**/**/*.md</exclude>
-            <exclude>**/**/*.sh</exclude>
-         </excludes>
-         <directoryMode>0755</directoryMode>
-         <fileMode>0644</fileMode>
-      </fileSet>
-      <fileSet>
-         <directory>${activemq.basedir}/examples</directory>
-         <outputDirectory>examples</outputDirectory>
-         <lineEnding>keep</lineEnding>
-         <includes>
-            <include>**/**/*.sh</include>
-         </includes>
-         <excludes>
-            <exclude>**/target/**</exclude>
-         </excludes>
-         <directoryMode>0755</directoryMode>
-         <fileMode>0755</fileMode>
-      </fileSet>
-      <fileSet>
-         <directory>${project.build.directory}/markdown-pages/examples</directory>
-         <outputDirectory>examples</outputDirectory>
-         <lineEnding>keep</lineEnding>
-         <directoryMode>0755</directoryMode>
-         <fileMode>0644</fileMode>
-      </fileSet>
       <!-- Include license and notice files -->
       <fileSet>
          <directory>${activemq.basedir}/artemis-distribution/src/main/resources/licenses/bin</directory>

diff --git a/artemis-distribution/src/main/resources/README.html b/artemis-distribution/src/main/resources/README.html
@@ -111,9 +111,11 @@ <h2>Stopping the Broker</h2>
 
 <h2>Documentation</h2>
 
-The broker comes shipped with an in depth user manual and a bunch of examples to help you get started.  The manual is shipped with the broker and can be accessed from the brokers website.  Start the broker then navigate to the <a href="http://localhost:8161">Apache ActiveMQ Artemis</a>.  Alternatively, you can browse all of the documentation online on the <a href="http://activemq.apache.org/artemis/">Apache ActiveMQ Artemis Website</a>.<br><br>
+The broker has an in depth user manual and a bunch of examples to help you get started.
 
-The examples are shipped inside the distribution folder under "examples"<br><br>
+The manual can be found in the documentation on the <a href="https://activemq.apache.org/components/artemis/documentation/">Apache ActiveMQ Artemis Website</a>.<br><br>
+
+The examples are can be found in the the <a href="https://github.com/apache/activemq-artemis-examples">Apache ActiveMQ Artemis Examples</a> github repository.<br><br><br><br>
 
 Release Notes for all version can be found <a href="https://issues.apache.org/jira/browse/ARTEMIS/?selectedTab=com.atlassian.jira.jira-projects-plugin:versions-panel">here</a>