diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 000000000..5b2e2441b --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,112 @@ +name: Build + +on: + push: + branches: [main] + pull_request: + branches: [main] + workflow_dispatch: + +# Cancel superseded PR runs. Pushes to main are never cancelled so every merge gets released. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +permissions: + contents: read + +jobs: + build: + name: Build / Test / Release + runs-on: windows-latest + timeout-minutes: 45 + permissions: + contents: write # create the GitHub release on main + checks: write # test result check run + pull-requests: write # test result PR comment + env: + GRADLE_OPTS: -Xmx3072m -Dfile.encoding=UTF-8 + steps: + - name: Checkout + uses: actions/checkout@v5 + with: + submodules: true + + - name: Set up Java 25 + uses: actions/setup-java@v5 + with: + distribution: temurin + java-version: "25" + + # Caches the Gradle wrapper and dependencies (replaces Azure's Cache@2 step). + - name: Set up Gradle + uses: gradle/actions/setup-gradle@v5 + with: + # Only main writes the cache so PR branches can't pollute it. + cache-read-only: ${{ github.ref != 'refs/heads/main' }} + + # build = compile + spotlessCheck + checkstyle + tests + JaCoCo report + - name: Build + run: ./gradlew build --stacktrace --console=plain + shell: bash + + - name: Publish test results + # The default variant of this action is a Linux-only Docker action; use the Windows one. + uses: EnricoMi/publish-unit-test-result-action/windows@v2 + if: ${{ !cancelled() }} + with: + files: build/test-results/test/TEST-*.xml + check_name: JUnit results + # Fork PRs get a read-only token and can't post checks/comments; don't fail on that. + comment_mode: ${{ github.event.pull_request.head.repo.fork && 'off' || 'changes' }} + continue-on-error: ${{ github.event.pull_request.head.repo.fork == true }} + + - name: Upload JaCoCo report + uses: actions/upload-artifact@v5 + if: ${{ !cancelled() }} + with: + name: jacoco-report + path: build/reports/jacoco/test/ + retention-days: 14 + if-no-files-found: warn + + - name: Build Javadoc + run: ./gradlew javadoc --stacktrace --console=plain + shell: bash + + - name: Upload Javadoc + uses: actions/upload-artifact@v5 + with: + name: javadoc + path: build/docs/javadoc + retention-days: 14 + + # Each push to main becomes a GitHub release tagged with its version. Robot projects + # download the jar straight from the release (see README "Using SeriouslyCommonLib"). + # Versions keep the old Azure feed's yyyyMMdd.N shape so they sort after older builds. + - name: Create GitHub release + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + shell: bash + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + export PUBLISH_VERSION="$(date -u +%Y%m%d).$(date -u +%H%M%S)" + ./gradlew jar sourcesJar javadocJar generatePomFileForMyPublicationPublication --console=plain + + out=build/release + mkdir -p "$out" + cp build/libs/SeriouslyCommonLib.jar "$out/SeriouslyCommonLib-$PUBLISH_VERSION.jar" + cp build/libs/SeriouslyCommonLib-sources.jar "$out/SeriouslyCommonLib-$PUBLISH_VERSION-sources.jar" + cp build/libs/SeriouslyCommonLib-javadoc.jar "$out/SeriouslyCommonLib-$PUBLISH_VERSION-javadoc.jar" + cp build/publications/myPublication/pom-default.xml "$out/SeriouslyCommonLib-$PUBLISH_VERSION.pom" + + gh release create "$PUBLISH_VERSION" "$out"/* \ + --target "$GITHUB_SHA" \ + --title "SeriouslyCommonLib $PUBLISH_VERSION" \ + --generate-notes + + { + echo "### Released \`xbot.common:SeriouslyCommonLib:$PUBLISH_VERSION\`" + echo "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/releases/tag/$PUBLISH_VERSION" + } >> "$GITHUB_STEP_SUMMARY" diff --git a/AGENTS.md b/AGENTS.md index acfc50e96..944be8c41 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,7 +25,7 @@ SeriouslyCommonLib/ ├── build.gradle # Gradle build (GradleRIO + Dagger + Checkstyle) ├── xbotcheckstyle.xml # Checkstyle ruleset ├── checkstyle_suppressions.xml # Checkstyle suppressions -├── azure-pipelines.yml # CI/CD (builds on main branch and PRs to main) +├── .github/workflows/build.yml # CI/CD (builds PRs to main; builds + releases main) └── vendordeps/ # WPILib vendor dependency JSON files ``` @@ -73,8 +73,9 @@ All commands use the Gradle wrapper from the repository root. ./gradlew --stop ``` -> **Note:** The CI pipeline runs `./gradlew build --stacktrace --info` on every PR targeting -> `main` and on every push to `main`. Always ensure `./gradlew build` passes before finalizing +> **Note:** CI (GitHub Actions, `.github/workflows/build.yml`) runs `./gradlew build` on every PR +> targeting `main` and on every push to `main`. Each push to `main` also creates a GitHub release +> (tag = version) with the jar, sources, Javadoc, and POM attached. Always ensure `./gradlew build` passes before finalizing > a change. ## Coding Conventions diff --git a/README.md b/README.md index 17bec9b16..882d7ab1d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Seriously Common Lib for FRC -[![Build Status](https://dev.azure.com/Team488/Team%20488%20Builds/_apis/build/status%2FTeam488.SeriouslyCommonLib?branchName=main)](https://dev.azure.com/Team488/Team%20488%20Builds/_build/latest?definitionId=1&branchName=main) -[![xbot.common:SeriouslyCommonLib package in XBot feed in Azure Artifacts](https://feeds.dev.azure.com/Team488/2ef6eee3-1df0-441a-9af8-5edc5c3cb203/_apis/public/Packaging/Feeds/XBot/Packages/1dc16f9c-8e55-4f41-ada6-7b73e2161843/Badge)](https://dev.azure.com/Team488/Team%20488%20Builds/_artifacts/feed/XBot/maven/xbot.common%2FSeriouslyCommonLib?preferRelease=true) +[![Build](https://github.com/Team488/SeriouslyCommonLib/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/Team488/SeriouslyCommonLib/actions/workflows/build.yml) +[![Latest release](https://img.shields.io/github/v/release/Team488/SeriouslyCommonLib?label=release)](https://github.com/Team488/SeriouslyCommonLib/releases/latest) ## Up-Front Warning @@ -37,6 +37,33 @@ We plan to continue maintaining this codebase throughout upcoming years as we de If you want to jump in, a good place to start is our [robot template](https://github.com/Team488/FRCRobotTemplate). It includes all the configuration, build scripts, and boilerplate needed to start adding functionality. We hope to develop full documentation, but in the meantime, feel free to open issues on this repo to ask us questions and provide feedback. You can also take a look at the [generated documentation](https://team488.github.io/SeriouslyCommonLib/). +### Using SeriouslyCommonLib in a robot project + +Every merge to `main` is published as a [GitHub release](https://github.com/Team488/SeriouslyCommonLib/releases) +tagged with its version (e.g. `20261107.193005`). Gradle can download the jar straight from the release, +with no Maven feed or credentials needed: + +```groovy +def SeriouslyCommonLibVersion = '20261107.193005' // pick a tag from the releases page + +repositories { + ivy { + name = 'SeriouslyCommonLibReleases' + url = 'https://github.com/Team488/SeriouslyCommonLib/releases/download/' + patternLayout { artifact '[revision]/[module]-[revision](-[classifier]).[ext]' } + metadataSources { artifact() } + content { includeGroup 'xbot.common' } + } +} + +dependencies { + implementation "xbot.common:SeriouslyCommonLib:${SeriouslyCommonLibVersion}" +} +``` + +Versions must be pinned exactly; ranges like `+` or `latest.release` don't work against release URLs. +Older versions (before the move to GitHub releases) remain on the XBot Azure Artifacts feed. + ## How's development going? We are currently in the process of modifying this library to get it ready as a robot platform. We plan to build on top of it in upcoming seasons to add functionality and fix bugs. Currently, it should be fully functional for testing using the template project, but there isn't much documentation available. More to come soon! diff --git a/azure-pipelines.yml b/azure-pipelines.yml deleted file mode 100644 index 3ea1791c5..000000000 --- a/azure-pipelines.yml +++ /dev/null @@ -1,97 +0,0 @@ -# Gradle -# Build your Java project and run tests with Gradle using a Gradle wrapper script. -# Add steps that analyze code, save build artifacts, deploy, and more: -# https://docs.microsoft.com/azure/devops/pipelines/languages/java - -trigger: - - main -pr: - - main - -jobs: - - job: Windows_64_Bit - pool: - vmImage: 'windows-latest' - variables: - GRADLE_USER_HOME: $(Build.SourcesDirectory)/build/.gradle - steps: - - checkout: self - displayName: 'Checkout sources' - submodules: true - clean: true - - task: JavaToolInstaller@0 - inputs: - versionSpec: '25' - jdkArchitectureOption: 'x64' - jdkSourceOption: 'PreInstalled' - - task: Cache@2 - inputs: - key: 'gradle | "$(Agent.OS)" | $(Build.SourcesDirectory)/build.gradle | $(Build.SourcesDirectory)/settings.gradle | $(Build.SourcesDirectory)/gradle/wrapper/gradle-wrapper.properties | $(Build.SourcesDirectory)/vendordeps/*' - path: $(GRADLE_USER_HOME) - displayName: 'Cache Gradle dependencies' - - task: Gradle@3 - displayName: 'Check code formatting (Spotless)' - inputs: - workingDirectory: '' - gradleWrapperFile: 'gradlew' - gradleOptions: '-Xmx3072m' - tasks: 'spotlessCheck --stacktrace' - publishJUnitResults: false - env: - GRADLE_USER_HOME: $(GRADLE_USER_HOME) - - task: Gradle@3 - inputs: - workingDirectory: '' - gradleWrapperFile: 'gradlew' - gradleOptions: '-Xmx3072m' - publishJUnitResults: true - testResultsFiles: '**/TEST-*.xml' - tasks: 'build --stacktrace --info' - env: - GRADLE_USER_HOME: $(GRADLE_USER_HOME) - - task: PublishCodeCoverageResults@2 - inputs: - codeCoverageTool: 'JaCoCo' - summaryFileLocation: 'build/reports/jacoco/test/jacocoTestReport.xml' - reportDirectory: 'build/reports/jacoco/test/html' - - task: MavenAuthenticate@0 - displayName: 'Maven Authenticate' - inputs: - artifactsFeeds: XBot - condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') - - task: Gradle@3 - displayName: 'Publish to Maven' - inputs: - workingDirectory: '' - gradleWrapperFile: 'gradlew' - gradleOptions: '-Xmx3072m' - tasks: 'publish --info' - publishJUnitResults: false - env: - GRADLE_USER_HOME: $(GRADLE_USER_HOME) - condition: eq(variables['Build.SourceBranch'], 'refs/heads/main') - - task: Gradle@3 - displayName: Generate Javadoc - inputs: - workingDirectory: '' - gradleWrapperFile: 'gradlew' - gradleOptions: '-Xmx3072m' - tasks: 'javadoc' - publishJUnitResults: false - env: - GRADLE_USER_HOME: $(GRADLE_USER_HOME) - - task: Gradle@3 - displayName: Stop gradle daemon - inputs: - workingDirectory: '' - gradleWrapperFile: 'gradlew' - gradleOptions: '-Xmx3072m' - tasks: '--stop' - publishJUnitResults: false - env: - GRADLE_USER_HOME: $(GRADLE_USER_HOME) - - task: PublishPipelineArtifact@0 - displayName: 'Publish javadoc as an artifact' - inputs: - artifactName: 'javadoc' - targetPath: 'build/docs/javadoc' diff --git a/build.gradle b/build.gradle index 6be0b4519..482555a2f 100644 --- a/build.gradle +++ b/build.gradle @@ -5,7 +5,6 @@ plugins { id 'scala' id 'checkstyle' id 'jacoco' - id "net.linguica.maven-settings" version "0.5" id 'com.diffplug.spotless' version '8.10.4' } @@ -235,17 +234,14 @@ publishing { myPublication(MavenPublication) { groupId 'xbot.common' artifactId 'SeriouslyCommonLib' - version System.getenv('BUILD_BUILDNUMBER') ?: '1.0.0' + // Set by .github/workflows/build.yml when releasing from main. + version System.getenv('PUBLISH_VERSION') ?: '1.0.0' artifact jar artifact sourcesJar artifact javadocJar - } - } - repositories { - maven { - url = 'https://pkgs.dev.azure.com/Team488/2ef6eee3-1df0-441a-9af8-5edc5c3cb203/_packaging/XBot/maven/v1' - name = 'XBot' } } + // Releases are published as GitHub releases by CI; this publication is only used for + // the release POM and for local `publishToMavenLocal`. }