Skip to content

Commit abc1bf7

Browse files
slominskirslominskir
committed
Usage Example
1 parent e12663d commit abc1bf7

File tree

13 files changed

+484
-1
lines changed

13 files changed

+484
-1
lines changed

‎.devcontainer/dev.yaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
services:
2+
#TODO: Your other containers go here!
3+
4+
dev:
5+
image: jeffersonlab/java-devcontainer:1.0.3
6+
hostname: dev
7+
container_name: dev
8+
volumes:
9+
- /var/run/docker.sock:/var/run/docker.sock

‎.devcontainer/devcontainer.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"dockerComposeFile": "dev.yaml",
3+
"service": "dev",
4+
"workspaceFolder": "/workspaces/java-workflows"
5+
}

‎.github/workflows/cd.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: CD
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths:
7+
- 'VERSION'
8+
tags-ignore:
9+
- '**'
10+
11+
jobs:
12+
release:
13+
uses: jeffersonlab/java-workflows/.github/workflows/gh-release.yml@v1
14+
with:
15+
files: build/Hi
16+
secrets: inherit
17+
18+
docs_publish:
19+
needs:
20+
- release
21+
uses: jeffersonlab/java-workflows/.github/workflows/gh-pages-publish.yml@v1
22+
with:
23+
semvertag: ${{ needs.release.outputs.semvertag }}
24+
secrets: inherit

‎.github/workflows/ci.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths-ignore:
7+
- 'VERSION'
8+
tags-ignore:
9+
- "v*.*.*"
10+
pull_request:
11+
branches: [ main ]
12+
workflow_dispatch:
13+
14+
permissions:
15+
contents: read
16+
17+
jobs:
18+
build:
19+
uses: jeffersonlab/java-workflows/.github/workflows/unit-ci.yml@v1

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
/.idea/
2+
/build/
3+
/.gradle/

‎README.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,44 @@
1-
# java workflows
1+
# java workflows <a href="https://codespaces.new/JeffersonLab/java-workflows"><img src="https://github.com/codespaces/badge.svg" height="20"></a>
22
GitHub action Java workflows
33

4+
## Reusable workflows
5+
46
| Name | Description |
57
|----------------------|----------------------------------|
68
| [gh-pages-publish.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/gh-pages-publish.yml) | Publish API docs to GitHub Pages |
79
| [gh-release.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/gh-release.yml) | Create a GitHub Release |
810
| [maven-publish.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/maven-publish.yml) | Publish an artifact on Maven Central |
911
| [unit-ci.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/unit-ci.yml) | Build and run Unit tests |
1012

13+
## How to use
14+
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:
15+
16+
| Name | Description |
17+
|---------------------------------------------------------------------------------------------|----------------------------------|
18+
| [ci.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/ci.yml) | Continuous Integration of an App/Lib |
19+
| [cd.yml](https://github.com/JeffersonLab/java-workflows/blob/main/.github/workflows/cd.yml) | Continuous Deployment of an App/Lib with GitHub release |
20+
21+
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])).
22+
23+
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.
24+
25+
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.
26+
27+
## Demo App
28+
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:
29+
30+
```
31+
gradlew build
32+
```
33+
34+
## Workflow Updates
35+
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):
36+
37+
```
38+
git tag -f v1
39+
git push --tags -f
40+
```
41+
1142
## See Also
1243
- [Other workflows](https://github.com/search?q=org%3Ajeffersonlab+topic%3Agh-action-workflow&type=repositories)
1344
- [Projects using this](https://github.com/search?q=org%3Ajeffersonlab+topic%3Ajava-workflows&type=repositories)

‎VERSION‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
0.0.1

‎build.gradle‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
plugins {
2+
id 'java-library'
3+
}
4+
5+
description = 'Java Workflows'
6+
group 'org.jlab'
7+
version new File("${projectDir}/VERSION").text.trim()
8+
ext.releaseDate = new Date().format('MMM dd yyyy')
9+
10+
tasks.withType(JavaCompile) {
11+
options.release = 8
12+
options.encoding = 'UTF-8'
13+
options.compilerArgs << "-Xlint:unchecked" << "-Xlint:deprecation"
14+
}
15+
16+
java {
17+
withJavadocJar()
18+
withSourcesJar()
19+
}
20+
21+
repositories {
22+
mavenCentral()
23+
}
24+
25+
dependencies {
26+
testImplementation 'junit:junit:4.13.2'
27+
}
28+
29+
test {
30+
testLogging {
31+
events "passed", "skipped", "failed"
32+
exceptionFormat "full"
33+
}
34+
}
35+
36+
task hello (type: JavaExec) {
37+
group 'Application'
38+
description 'Hello World Test'
39+
mainClass = 'org.jlab.workflows.Hello'
40+
classpath = sourceSets.test.runtimeClasspath
41+
}
42+
43+
javadoc {
44+
options.overview = "src/overview.html"
45+
options.source = 8
46+
options.with {
47+
links 'https://devdocs.io/openjdk~8/'
48+
}
49+
}

‎gradle/wrapper/gradle-wrapper.jar‎

58.4 KB
Binary file not shown.

‎gradle/wrapper/gradle-wrapper.properties‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
distributionBase=GRADLE_USER_HOME
2+
distributionPath=wrapper/dists
3+
distributionUrl=https\://services.gradle.org/distributions/gradle-7.4-bin.zip
4+
zipStoreBase=GRADLE_USER_HOME
5+
zipStorePath=wrapper/dists

0 commit comments

Comments
 (0)