Usage Example

.devcontainer/dev.yaml

@@ -0,0 +1,9 @@
+services:
+  #TODO: Your other containers go here!
+
+  dev:
+    image: jeffersonlab/java-devcontainer:1.0.3
+    hostname: dev
+    container_name: dev
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock

.devcontainer/devcontainer.json

@@ -0,0 +1,5 @@
+{
+  "dockerComposeFile": "dev.yaml",
+  "service": "dev",
+  "workspaceFolder": "/workspaces/java-workflows"
+}

.github/workflows/cd.yml

@@ -0,0 +1,24 @@
+name: CD
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'VERSION'
+    tags-ignore:
+      - '**'
+
+jobs:
+  release:
+    uses: jeffersonlab/java-workflows/.github/workflows/gh-release.yml@v1
+    with:
+      files: build/Hi
+    secrets: inherit
+
+  docs_publish:
+    needs:
+      - release
+    uses: jeffersonlab/java-workflows/.github/workflows/gh-pages-publish.yml@v1
+    with:
+      semvertag: ${{ needs.release.outputs.semvertag }}
+    secrets: inherit

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+    paths-ignore:
+      - 'VERSION'
+    tags-ignore:
+      - "v*.*.*"
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    uses: jeffersonlab/java-workflows/.github/workflows/unit-ci.yml@v1

.gitignore

@@ -1 +1,3 @@
 /.idea/
+/build/
+/.gradle/

README.md

@@ -1,13 +1,44 @@
-# java workflows
+# java workflows <a href="https://codespaces.new/JeffersonLab/java-workflows"><img src="https://github.com/codespaces/badge.svg" height="20"></a>
 GitHub action Java workflows
 
+## Reusable workflows
+
 | Name                 | Description                      |
 |----------------------|----------------------------------|
 | [gh-pages-publish.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/gh-pages-publish.yml) | Publish API docs to GitHub Pages |
 | [gh-release.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/gh-release.yml) | Create a GitHub Release |
 | [maven-publish.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/maven-publish.yml) | Publish an artifact on Maven Central |
 | [unit-ci.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/unit-ci.yml) | Build and run Unit tests |
 
+## How to use
+This project uses it's own workflows in order to test them (the Java App/Lib is just a demo/example).  Copy and paste one or more of the following files into your project `.github/workflows` directory and update parameters accordingly:
+
+| Name                                                                                        | Description                      |
+|---------------------------------------------------------------------------------------------|----------------------------------|
+| [ci.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/ci.yml) | Continuous Integration of an App/Lib |
+| [cd.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/cd.yml) | Continuous Deployment of an App/Lib with GitHub release |
+
+The `ci` workflow invokes `unit-ci` to configure, build, and unit test.   The `ci` workflow can be customized with docker commands to launch containers and run integration tests ([Java Example](https://github.com/JeffersonLab/myquery/blob/e47681393f9a7a900dc1f0a932b6271bfa6356ed/.github/workflows/ci.yml#L20-L44])).
+
+The `cd` workflow invokes `gh-release` and optionally `gh-pages-publish`.  The `gh-release` workflow uses the VERSION file to determine which tag to create.  The `cd` workflow generally should monitor the VERSION file for changes to trigger the workflow.
+
+The `gh-pages-publish` workflow creates docs on GitHub Pages.  For example, the demo Lib docs are here: [javadoc API docs](https://jeffersonlab.github.io/java-workflows/).  The workflow creates a new directory in the [gh-pages](https://github.com/JeffersonLab/java-workflows/tree/gh-pages) branch of your project for each release using the semver name and copies the auto generated API docs there.  An index HTML with JavaScript can then use the GitHub API to lookup the directories in the branch and list them in the index.  This means there is a one-time setup for each project where you need to commit and push the index.html, index.js, and .nojekyll files.  The path to the docs are then obtained at `https://jeffersonlab.github.io/project/` where project is your project name.  Example [setup commit](https://github.com/JeffersonLab/cxx-workflows/commit/36de0f35037c3b14834bbfbbb9e7784f2e70eebe) - notice first line of index.js must be customized with project name.
+
+## Demo App
+This project includes a `Hello World` Java app to demonstrate the workflow.  Use the [java-devcontainer](https://github.com/JeffersonLab/java-devcontainer) to configure, build, and test:
+
+```
+gradlew build
+```
+
+## Workflow Updates
+Workflows are versioned in semver just as with regular software, however, the GitHub Action workflows convention is to reference a major version number such that backwards compatible minor and patch updates are received automatically.  This means a separate major tag such as `v1` must be moved after each release.  To move a major tag after a release execute (`v1` shown):
+
+```
+git tag -f v1
+git push --tags -f
+```
+
 ## See Also
 - [Other workflows](https://github.com/search?q=org%3Ajeffersonlab+topic%3Agh-action-workflow&type=repositories)
 - [Projects using this](https://github.com/search?q=org%3Ajeffersonlab+topic%3Ajava-workflows&type=repositories)

VERSION

@@ -0,0 +1 @@
+0.0.1

build.gradle

@@ -0,0 +1,49 @@
+plugins {
+    id 'java-library'
+}
+
+description = 'Java Workflows'
+group 'org.jlab'
+version new File("${projectDir}/VERSION").text.trim()
+ext.releaseDate = new Date().format('MMM dd yyyy')
+
+tasks.withType(JavaCompile) {
+    options.release = 8
+    options.encoding = 'UTF-8'
+    options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"
+}
+
+java {
+    withJavadocJar()
+    withSourcesJar()
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    testImplementation 'junit:junit:4.13.2'
+}
+
+test {
+    testLogging {
+        events "passed", "skipped", "failed"
+        exceptionFormat "full"
+    }
+}
+
+task hello (type: JavaExec) {
+    group 'Application'
+    description 'Hello World Test'
+    mainClass = 'org.jlab.workflows.Hello'
+    classpath = sourceSets.test.runtimeClasspath
+}
+
+javadoc {
+    options.overview = "src/overview.html"
+    options.source = 8
+    options.with {
+        links 'https://devdocs.io/openjdk~8/'
+    }
+}

gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.4-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists