Merge pull request #477 from KyleAure/fix-spec-generation

Help automate specification project release review

.github/ISSUE_TEMPLATE/release.yml

@@ -51,6 +51,8 @@ body:
           #### Follow up
             - [ ] [Email the Concurrency Mailing list to have a Jakarta Steering Committee member promote the TCK Distribution publically](https://accounts.eclipse.org/mailing-list/cu-dev)
               - via [Jenkins build](https://ci.eclipse.org/jakartaee-spec-committee/job/promote-release/)
+            - [ ] [Create pull request to https://github.com/jakartaee/specifications](https://github.com/jakartaee/specifications/blob/master/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md)
+              - upload [generated specification documentation](https://github.com/jakartaee/concurrency/actions/workflows/specification.yml)
             - [ ] Update versions in non-build files, such as:
               Documentation:
               - [tck/README.adoc](https://github.com/jakartaee/concurrency/tree/main/tck#getting-the-tck)

.github/workflows/specification.yml

@@ -0,0 +1,42 @@
+# This workflow automates the creation of Specification Documents
+# which will be copied into https://github.com/jakartaee/specifications
+
+name: Generate specification documentation
+
+on: 
+    workflow_dispatch:
+        inputs:
+            specVersion:
+                description: 'Major and Minor level of release. Example: 3.1'
+                required: true
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout source
+      uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
+    - name: Set up JDK 17
+      uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 # v4.2.1
+      with:
+        java-version: 17
+        distribution: 'temurin'
+        cache: maven
+    - name: Generate specification docs
+      #TODO remove -Pstaging once all Jakarta EE 11 dependencies are GA
+      run: |
+        mvn package -Pstaging --file api/pom.xml -Dspec.version=${{ github.event.inputs.specVersion }}
+        mvn package -Pstaging --file specification/pom.xml -Dstatus=FINAL -Dspec.version=${{ github.event.inputs.specVersion }}
+    - name: Assemble documentation
+      run: |
+        mkdir documentation/
+        cp specification/target/generated-docs/jakarta-concurrency-spec-${{ github.event.inputs.specVersion }}.pdf   documentation/jakarta-concurrency-spec-${{ github.event.inputs.specVersion }}.pdf
+        cp specification/target/generated-docs/jakarta-concurrency-spec-${{ github.event.inputs.specVersion }}.html  documentation/jakarta-concurrency-spec-${{ github.event.inputs.specVersion }}.html
+        cp -r api/target/apidocs/ documentation/apidocs
+    - name: Upload documentation
+      uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1
+      with:
+        name: Specification Documentation
+        path: documentation/
+        if-no-files-found: error

api/README.md

@@ -8,12 +8,18 @@ Building
 
 Prerequisites:
 
-* JDK8+
-* Maven 3.0.3+
+* JDK 17+
+* Maven 3.8.0+
 
 Build and test the API:
 
 `mvn package`
 
+Build the API for publication:
+
+`mvn package -file api/pom.xml -Dspec.version=X.Y`
+
+Where `X.Y` indicates the Major and Minor version. Example: `3.1`
+
 Look for any error in the checkstye:
 - target/checkstyle/checkstyle.html

api/pom.xml

@@ -42,6 +42,12 @@
         <url>https://github.com/jakartaee/concurrency</url>
     </scm>
 
+    <properties>
+        <!-- default is the same for backward compatibility reason
+            Easy to override when building with a system property -->
+        <spec.version>3.1</spec.version>
+    </properties>
+
     <dependencies>
         <dependency>
             <groupId>jakarta.interceptor</groupId>
@@ -78,9 +84,9 @@
                 <version>2.2</version>
                 <configuration>
                     <spec>
-                        <specVersion>3.1</specVersion>
+                        <specVersion>${spec.version}</specVersion>
                         <specImplVersion>${project.version}</specImplVersion>
-                        <apiPackage>jakarta.enterprise.concurrent</apiPackage>
+                        <apiPackage>${project.groupId}</apiPackage>
                     </spec>
                 </configuration>
                 <executions>
@@ -161,7 +167,7 @@
                             <description>Jakarta Concurrency API documentation</description>
                             <doctitle>Jakarta Concurrency API documentation</doctitle>
                             <windowtitle>Jakarta Concurrency API documentation</windowtitle>
-                            <header><![CDATA[<br>Jakarta Concurrency API v${project.version}]]></header>
+                            <header><![CDATA[<br>Jakarta Concurrency API v${spec.specification.version}]]></header>
                             <bottom><![CDATA[
 Comments to: <a href="mailto:cu-dev@eclipse.org">cu-dev@eclipse.org</a>.<br>
 Copyright &#169; 2020, 2024 Eclipse Foundation. All rights reserved.<br>

specification/README.md

@@ -8,13 +8,20 @@ Building
 
 Prerequisites:
 
-* JDK8+
-* Maven 3.0.3+
+* JDK 17+
+* Maven 3.8.5+
 
 Run the full build:
 
 `mvn install`
 
+Run the build to generate specifciation documentation for publication:
+
+`mvn package --file specification/pom.xml -Dstatus=FINAL -Dspec.version=X.Y`
+
+Where `FINAL` indicates the status of this documentation.
+Where `X.Y` indicates the Major and Minor version. Example: `3.1`
+
 Locate the html files:
 - target/generated-docs/Concurrency.html
 

specification/pom.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  
-    Copyright (c) 2017, 2019 Oracle and/or its affiliates. All rights reserved.
+    Copyright (c) 2017, 2024 Oracle and/or its affiliates. All rights reserved.
  
     This program and the accompanying materials are made available under the
     terms of the Eclipse Public License v. 2.0, which is available at
@@ -20,15 +20,12 @@
     <modelVersion>4.0.0</modelVersion>
 
     <parent>
-        <groupId>org.eclipse.ee4j</groupId>
-        <artifactId>project</artifactId>
-        <version>1.0.9</version>
-        <relativePath />
+        <groupId>jakarta.enterprise.concurrent</groupId>
+        <artifactId>jakarta.enterprise.concurrent.parent</artifactId>
+        <version>3.1.0-SNAPSHOT</version>
     </parent>
 
-    <groupId>jakarta.enterprise.concurrent</groupId>
     <artifactId>concurrency-spec</artifactId>
-    <version>3.0-SNAPSHOT</version>
     <packaging>pom</packaging>
 
     <name>Jakarta Concurrency Specification</name>
@@ -39,6 +36,7 @@
         <url>https://github.com/eclipse-ee4j/jakarta-concurrency</url>
         <tag>HEAD</tag>
     </scm>
+
     <distributionManagement>
         <site>
             <url>scm:git:git@github.com:eclipse-ee4j/jakarta-concurrency.git</url>
@@ -48,12 +46,15 @@
     <properties>
         <site.output.dir>${project.build.directory}/staging</site.output.dir>
         <maven.site.skip>true</maven.site.skip>
+
         <asciidoctor.maven.plugin.version>3.0.0</asciidoctor.maven.plugin.version>
         <asciidoctorj.version>2.5.12</asciidoctorj.version>
         <asciidoctorj.pdf.version>2.3.15</asciidoctorj.pdf.version>
         <jruby.version>9.4.6.0</jruby.version> 
+
         <!-- status: DRAFT, BETA, etc., or blank for final -->
         <status>DRAFT</status>
+
         <maven.build.timestamp.format>MMMM dd, yyyy</maven.build.timestamp.format>
         <revisiondate>${maven.build.timestamp}</revisiondate>
 

tck/README.md

@@ -15,8 +15,8 @@ This guide will help you build and run the TCK on a supported Jakarta EE Applica
 ### System Requirements
 You will need to download and install the following software before you begin.
 
-- [JDK 11 or higher](https://adoptopenjdk.net/?variant=openjdk11)
-- [Maven 3.6.0 or higher](https://maven.apache.org/download.cgi)
+- JDK 17 or higher
+- [Maven 3.8.0 or higher](https://maven.apache.org/download.cgi)
 - Jakarta EE Application Server or Container [Glassfish, Open Liberty, JBoss, WebLogic, etc.]
 
 ### Testing Framework