diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index d3ca852..2b31fb8 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,4 +1,4 @@ contact_links: - name: ❓ Questions and Help πŸ€” - url: https://discord.gg/tbd (/add your discord channel if applicable) + url: https://discord.gg/block (/add your discord channel if applicable) about: This issue tracker is not for support questions. Please refer to the community for more help. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 805f8c1..55e0c7f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,7 +3,6 @@ # * Run tests # # In the Ubuntu environment only, to avoid double uploads from MacOS, it also: -# * Uploads Test reports to BuildKite # * Uploads Coverage reports to CodeCov # * Publishes (deploys) to Block's SaaS Artifactory instance as version commit-$shortSHA-SNAPSHOT # @@ -46,7 +45,7 @@ jobs: # Maven "test" lifecycle will build and test only on MacOS mvn test - # On Ubuntu we build, test, verify, and deploy: Code Coverage, Test Vectors, and SNAPSHOT artifacts to TBD Artifactory + # On Ubuntu we build, test, verify, and deploy: Code Coverage, Test Vectors, and SNAPSHOT artifacts to Block Artifactory build-test-deploy-snapshot-ubuntu: runs-on: ubuntu-latest steps: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 402ed54..b9f9ed9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -18,7 +18,7 @@ on: description: '(Required) The version to release. Must be a real version, not a SNAPSHOT (ie. ending in "-SNAPSHOT"). For example "1.0.0", "1.0.0-alpha-1".' required: true jobs: - release-publish-tbd-artifactory: + release-publish-block-artifactory: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/tests-publish.yml b/.github/workflows/tests-publish.yml deleted file mode 100644 index 22b2ad0..0000000 --- a/.github/workflows/tests-publish.yml +++ /dev/null @@ -1,58 +0,0 @@ -name: Publish Tests Report - -on: - workflow_run: - workflows: ["SDK Kotlin CI"] - types: - - completed - -jobs: - comment-action: - name: Publish Tests Report - runs-on: ubuntu-latest - - steps: - - name: Download TBDocs Report - uses: dawidd6/action-download-artifact@v2 - with: - run_id: ${{ github.event.workflow_run.id }} - name: tests-report-junit - path: ./ - - - name: Publish Tests Results - env: - BUILDKITE_ANALYTICS_TOKEN: ${{ secrets.BUILDKITE_ANALYTICS_TOKEN }} - WORKFLOW_RUN_ID: ${{ github.event.workflow_run.id }} - run: | - declare -a projects=("common" "credentials" "crypto" "dids") - - for project in "${projects[@]}"; do - # Find Tests Reports in each project and store them in an array - files=($(find "${project}/target/surefire-reports" -name '*.xml')) - - # Check if files array is empty - if [ ${#files[@]} -eq 0 ]; then - echo "No Tests files found in ${project} directory!" - exit 1 - else - echo "Found ${#files[@]} XML files in ${project} directory, proceeding with upload..." - fi - - # Iterate over the files and upload each one - for file in "${files[@]}"; do - echo "Uploading ${file} to BuildKite..." - curl \ - -X POST \ - --fail-with-body \ - -H "Authorization: Token token=\"$BUILDKITE_ANALYTICS_TOKEN\"" \ - -F "data=@$file" \ - -F "format=junit" \ - -F "run_env[CI]=github_actions" \ - -F "run_env[key]=$GITHUB_ACTION-$GITHUB_RUN_NUMBER-$GITHUB_RUN_ATTEMPT" \ - -F "run_env[number]=$GITHUB_RUN_NUMBER" \ - -F "run_env[branch]=$GITHUB_REF" \ - -F "run_env[commit_sha]=$GITHUB_SHA" \ - -F "run_env[url]=https://github.com/$GITHUB_REPOSITORY/actions/runs/$WORKFLOW_RUN_ID" \ - https://analytics-api.buildkite.com/v1/uploads - done - done diff --git a/CODEOWNERS b/CODEOWNERS index 21ecf13..c0742c6 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -9,7 +9,7 @@ # The format is described: https://github.blog/2017-07-06-introducing-code-owners/ # These owners will be the default owners for everything in the repo. -* @GITHUB_USER_NAME_GOES_HERE +* @ALRubinger # ----------------------------------------------- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 95b8a6f..a808078 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,183 +1,192 @@ -# Contribution Guide +# Contribution Guide -There are many ways to be an open source contributor, and we're here to help you on your way! You may: +## Build Prerequisites -* Propose ideas in our - [discord](https://discord.gg/tbd) -* Raise an issue or feature request in our [issue tracker](LINK_HERE) ___***FIX LINK AND REMOVE THIS NOTICE***___ -* Help another contributor with one of their questions, or a code review -* Suggest improvements to our Getting Started documentation by supplying a Pull Request -* Evangelize our work together in conferences, podcasts, and social media spaces. +### Hermit -This guide is for you. +This project uses [Hermit](https://cashapp.github.io/hermit) to +manage the environment like Maven and Java versions. +See [this page](https://cashapp.github.io/hermit/usage/get-started/) to set up Hermit on your machine - make sure to +download the open source build and activate it for the project. -## Development Prerequisites +Once you've installed Hermit and before running builds on this repo, +run from the root of this repo: -___***UPDATE TABLE OF PROJECT DEPS AND INSTALLATION NOTES***___ +```shell +source ./bin/activate-hermit +``` -| Requirement | Tested Version | Installation Instructions | -|-------------|----------------|------------------------------------------------------| -| Go | 1.17.6 |[go.dev](https://go.dev/doc/tutorial/compile-install) | -| Mage | 1.12.1 |[magefile.org](https://magefile.org/) | -| Java | 17.0.2 | Below, recommended via [SDKMan](https://sdkman.io) | +This will set your environment up correctly in your terminal emulator. -### Go +## Building with Maven -This project is written in Go, a modern, open source programming language. +This project is built with the +[Maven Project Management](https://maven.apache.org/) tool. +It is installed automatically via Hermit above. -You may verify your `go` installation via the terminal: +If you want to build an artifact on your local filesystem, you can do so by running the +following command - either at the top level or in +any of the subprojects: -``` -$> go version -go version go1.17.6 darwin/amd64 +```shell +mvn clean verify ``` -If you do not have go, we recommend installing it by: +This will first clean all previous builds and compiled code, then: +compile, test, and build the artifacts in each of the submodules +of this project in the `$moduleName/target` directory. -#### MacOS +If you'd like to skip packaging and test only, run: -##### Homebrew -``` -$> brew install go +```shell +mvn test ``` -#### Linux - -See the [Go Installation Documentation](https://go.dev/doc/install). - -### Mage +You may also run a single test; `cd` into the submodule of choice, +then use the `-Dtest=` parameter to denote which test to run, for example: -The build is run by Mage. +```shell +cd impl; \ +mvn test -Dtest=TestClassName +``` -You may verify your `mage` installation via the terminal: +To install builds into your local Maven repository, run from the root: -``` -$> mage --version -Mage Build Tool 1.12.1 -Build Date: 2021-12-15T21:00:02Z -Commit: 2f1ec40 -built with: go1.17.6 +```shell +mvn install ``` -#### MacOS +For more, see the documentation on the [Maven Lifecycle](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html). -##### Homebrew +## Release -``` -$> brew install mage -``` +### SNAPSHOT Releases -#### Linux +In Java we use the SNAPSHOT convention to build and publish a +pre-release package that can be consumed for +preview/testing/development purposes. -Installation instructions are on the [Magefile home page](https://magefile.org/). +These `SNAPSHOT`s are generated and published **AUTOMATICALLY** whenever +there's a new push to `main` or on a PR. The SNAPSHOT will be given +version with format `commit-$shortSHA-SNAPSHOT`, for example +`commit-00b12aa-SNAPSHOT` and is available from the +[Block OSS Snapshots Repository](https://blockxyz.jfrog.io/artifactory/block-oss-snapshots-maven2/). -### Java +If you want to manually kick that off to preview some changes introduced in a branch, or for some reason regenerate the same snapshot: -This project is written in Java, a typesafe, compiled programming language. +1. Open the `CI` Workflow on the `Actions` tab in GitHub, press the **Run workflow button** selecting the branch you want to generate the snapshot from. -You may verify your `java` installation via the terminal by running `java -version`. +2. In the version field, insert the current version, a short meaningful identifier and the `-SNAPSHOT` suffix, ie: -If you do not have Java, we recommend installing it -via [SDKMan](https://sdkman.io/install). This is a project which will allow you -to easily install the Java Development Kit (JDK), runtime (JRE), and related frameworks, -build tools, and runtimes. + - 0.11.0.pr123-SNAPSHOT + - 0.11.0.shortsha-SNAPSHOT + - 0.11.0.fixsomething-SNAPSHOT -After you've installed SDKMan, you may install Java: +3. Run workflow! -#### SDKMan (cross-platform instructions) +You **MUST** use the `-SNAPSHOT` suffix, otherwise it's not a valid preview `SNAPSHOT` and it will be rejected. -```shell -$> sdk install java - ... -Do you want java 17.0.2-open to be set as default? (Y/n): Y -Setting java 17.0.2-open as default. -``` +`SNAPSHOT`s will be available in [Block's OSS Artifactory `block-oss-snapshots-maven2` Repository](https://blockxyz.jfrog.io/artifactory/block-oss-snapshots-maven2). +Consuming projects may bring in these `SNAPSHOT` +dependencies by configuring the Block OSS Artifactory repo, +for instance in `pom.xml` like: -You may test your installation: +```shell + + + block-oss-snapshots + block-oss-snapshots + + false + + + true + + https://blockxyz.jfrog.io/artifactory/block-oss-snapshots-maven2/ + + +``` + +...or, in Gradle's `gradle.settings.kts`, like: ```shell -$> java -version -openjdk version "17.0.2" 2022-01-18 -OpenJDK Runtime Environment (build 17.0.2+8-86) -OpenJDK 64-Bit Server VM (build 17.0.2+8-86, mixed mode, sharing) +dependencyResolutionManagement { + repositories { + mavenCentral() + // Thirdparty dependencies of Block OSS projects not in Maven Central + maven("https://blockxyz.jfrog.io/artifactory/block-oss-snapshots-maven2/") + } +} ``` ---- -**NOTE** - -You may additionally look for other Java versions to install by running `sdk list java`: +### Releasing and Publishing New Versions -...or other installation candidates like Apache Ant, Apache Maven, etc, by running `sdk list`. +To release a new version, execute the following steps: -Consult the SDKMan documentation for more info. +1. Open the `Release and Publish` Workflow on the `Actions` tab in GitHub, press the **Run workflow button** selecting the branch you want to generate the snapshot from. ---- +2. In the version field, declare the version to be released. ie: -## Build (Mage) - -``` -$> mage build -``` + - 0.15.2 + - 0.17.0-alpha-3 + - 1.6.3 -## Build (Java / Gradle) +**Choose an appropriate version number based on [semver](https://semver.org/) rules. Remember that versions are immutable once published to Maven Central; they cannot be altered or removed.** -### macOS / Linux -```shell -$> ./gradlew build -``` +3. Press the `Run workflow` button and leave the main branch selected (unless its a rare case where you don't want to build from the main branch for the release). -### Windows -```shell -$> gradlew.bat build -``` +4. This: -## Test (Mage) +- Builds +- Tests +- Creates artifacts for binaries and sources +- Signs artifacts with GPG Key +- Tags git with release number "v$version" +- Keeps development version in the pom.xml to 0.0.0-main-SNAPSHOT +- Pushes changes to git +- Publishes to Maven Central +- Creates GitHub Release "v$version" -``` -$> mage test -``` +### Publishing a `SNAPSHOT` from a Local Dev Machine -## Test (Java / Gradle) +Please take care to only publish `-SNAPSHOT` builds (ie. +when the `` field of the `pom.xml` ends in +`-SNAPSHOT`.) unless there's good reason +to deploy a non-`SNAPSHOT` release. Releases are typically handled via automation +in GitHub Actions s documented above. -### macOS / Linux -```shell -$> ./gradlew test -``` +To deploy to Block's Artifactory instance for sharing with others, you +need your Artifactory username and password handy (available to Block-employed engineers). +Set environment variables: -### Windows ```shell -$> gradlew.bat test +export ARTIFACTORY_USERNAME=yourUsername; \ +export ARTIFACTORY_PASSWORD=yourPassword ``` ---- -**NOTE** - -You may also combine Gradle build targets in one call, like: +...then run: ```shell -$> ./gradlew clean build test +mvn deploy --settings .maven_settings.xml ``` ---- - ## Communications ### Issues Anyone from the community is welcome (and encouraged!) to raise issues via -[GitHub Issues](LINK_HERE) ___***FIX LINK AND REMOVE THIS NOTICE***___. +[GitHub Issues](https://github.com/block/example-java-kotlin-maven-multimodule/issues). ### Discussions -Design discussions and proposals take place in our [discord](https://discord.gg/tbd). +Design discussions and proposals take place in GitHub Issues, above. -We advocate an asynchronous, written debate model - so write up your thoughts and invite the community to join in! +We advocate an asynchronous, written debate model - +so write up your thoughts and invite the community to join in! ### Continuous Integration -Build and Test cycles are run on every commit to every branch on [CircleCI](LINK_HERE). - - ___***FIX LINK ABOVE AND REMOVE THIS NOTICE***___ +Build and Test cycles are run on every commit to every branch on GitHub Actions. ## Contribution diff --git a/README.md b/README.md index 8cc8f9e..9798a03 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,88 @@ -# $PROJECT_NAME README +# Java Maven Multimodule Example -Congrats, project leads! You got a new project to grow! +This project kickstarts your work in a new Java/Maven project. +It should get you building as quickly as possible - with best practices +and services baked in. It's designed for the Block Open Source Program, and may +be adapted for other contexts. + +## Features +* Multimodule Maven project structure with 2 built-in modules: `api` and `impl`. +* [Hermit](https://cashapp.github.io/hermit/) managed environment (Java, Maven) +* GitHub Actions for Continuous Integration: + * Testing in both MacOS and Ubuntu environments + * Every commit to `main` published as `SNAPSHOT` in Block Artifactory + * Static Analysis ([CodeQL](https://codeql.github.com/)) + * License scanning ([FOSSA](https://fossa.com/)) + * Security Vulnerability detection for dependencies ([FOSSA](https://fossa.com/)) + * Automatic dependency upgrades ([Renovate](https://github.com/renovatebot/renovate)) + * Release and Publishing to [Maven Central](https://central.sonatype.com/) + +## Usage + +To build a project using this template as a base: +1. [Create a new repository](https://github.com/organizations/block/repositories/new). + +image + +2. Select +`block/example-java-kotlin-maven-multimodule` as the `Repository template`. + +image + +## Preparing Your Project from This Template + +There are a few steps you'll need to take from this +quickstart template to get your project ready for action. + +### πŸ—ΊοΈ Change the Maven Coordinates + +This example has `groupID` of `xyz.block` and `artifactId`s +of `java-kotlin-maven-example-*`. You'll need to update all `pom.xml` files: + +* `./pom.xml` +* `./api/pom.xml` +* `./impl/pom.xml` + +...to reflect your desired `artifactId`s. Note that changing the `groupId` may +render your project unable to publish into Maven Central; the account we use +to publish is cleared for the `xyz.block` namespace. +Block employees may assistance by +[opening an internal issue](https://github.com/squareup/ospo/issues/new/choose) with the +Open Source Program Office if they need to use +a different `groupId`. + +### πŸ”‘ Get access to required GitHub Actions Secrets + +The workflows on this project rely on GitHub Actions secrets, +environment variables, to run the build. The Open Source Program Office +team will, for security purposes, make these secrets available to your +project. The variables in question are: + +* `SONATYPE_USERNAME` - A token tied to the Block OSS Sonatype account +* `SONATYPE_PASSWORD` - Password for the above +* `ARTIFACTORY_USERNAME` - User for the Block OSS Artifactory instance used to publish `SNAPSHOT`s on each build +* `ARTIFACTORY_PASSWORD` - Password for the above +* `GPG_SECRET_KEY` - Key used for signing releases +* `GPG_SECRET_PASSPHRASE` - Passphrase for above + +Block employees may request access to these by +[opening an internal issue](https://github.com/squareup/ospo/issues/new/choose) with the +Open Source Program Office. + +### πŸš€ Get Building! + +Go get 'em. 🀘🏻🀘🏼🀘🏽🀘🏾🀘🏿 + +Instructions are in [`CONTRIBUTING.md`](./CONTRIBUTING.md). + +--- + +# README Template + +This is the part you adapt for your project's audience. This stub is meant to help you form a strong community around your work. It's yours to adapt, and may -diverge from this initial structure. Just keep the files seeded in this repo, and the rest is yours to evolve! +diverge from this initial structure. Just keep the files seeded in this repo, and the rest is yours to evolve! ## Introduction