From 429f93da929c5d9d9aef0cd2563c00a90173fbb5 Mon Sep 17 00:00:00 2001 From: Claudine Date: Sat, 22 Mar 2025 18:16:04 +0000 Subject: [PATCH 1/4] test build gradle with workflow --- .github/workflows/release.yml | 2 +- build.gradle.kts | 9 ++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8a93c24..ea1d3e2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -25,7 +25,7 @@ jobs: gradle-version: 8.5 - name: Build with Gradle id: build - run: gradle buildReleaseArtifacts + run: gradle -PprettyVersion=vtesttag buildReleaseArtifacts - name: Release uses: softprops/action-gh-release@v2 with: diff --git a/build.gradle.kts b/build.gradle.kts index 1f3b579..f0b749d 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -41,7 +41,14 @@ group = "com.myDomain" // - MINOR: Increases when you add new features that are backward-compatible. // - PATCH: Increases when you make backward-compatible bug fixes. // You can update these numbers as you release new versions of your library. -version = "1.0.0" +// the following conditional allows for the version to be overwritten by a Github release +// via the release workflow, which defines a property named "prettyVersion" + +if (project.hasProperty("prettyVersion")) { + version = project.property("prettyVersion").toString().trimStart('v') +} else { + version = "1.0.0" +} // The location of your sketchbook folder. The sketchbook folder holds your installed // libraries, tools, and modes. It is needed if you: From ecad5de61e5bea8ebc3c3ed900d2f63423097f51 Mon Sep 17 00:00:00 2001 From: Claudine Date: Sat, 22 Mar 2025 18:30:51 +0000 Subject: [PATCH 2/4] test for v --- .github/workflows/release.yml | 2 +- build.gradle.kts | 14 ++++++++++---- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ea1d3e2..1d5f1b2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -25,7 +25,7 @@ jobs: gradle-version: 8.5 - name: Build with Gradle id: build - run: gradle -PprettyVersion=vtesttag buildReleaseArtifacts + run: gradle -PgithubReleaseTag=vtesttag buildReleaseArtifacts - name: Release uses: softprops/action-gh-release@v2 with: diff --git a/build.gradle.kts b/build.gradle.kts index f0b749d..41b6b06 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -42,12 +42,18 @@ group = "com.myDomain" // - PATCH: Increases when you make backward-compatible bug fixes. // You can update these numbers as you release new versions of your library. // the following conditional allows for the version to be overwritten by a Github release -// via the release workflow, which defines a property named "prettyVersion" +// via the release workflow, which defines a property named "githubReleaseTag" + +version = if (project.hasProperty("githubReleaseTag")) { + // remove leading "v" from tag if present + if (project.property("githubReleaseTag").toString().substring(0,1) == "v") { + project.property("githubReleaseTag").toString().drop(1) + } else { + project.property("githubReleaseTag").toString() + } -if (project.hasProperty("prettyVersion")) { - version = project.property("prettyVersion").toString().trimStart('v') } else { - version = "1.0.0" + "1.0.0" } // The location of your sketchbook folder. The sketchbook folder holds your installed From 6541798c6d04fc89703f5b8a69c8e1ee7f4c7a5c Mon Sep 17 00:00:00 2001 From: Claudine Date: Sat, 22 Mar 2025 18:52:04 +0000 Subject: [PATCH 3/4] simplify, and docs --- .github/workflows/release.yml | 2 +- build.gradle.kts | 9 +++------ docs/develop.md | 28 ++++++++++++++++------------ docs/release.md | 12 ++++++++++-- 4 files changed, 30 insertions(+), 21 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1d5f1b2..b1e73c2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -25,7 +25,7 @@ jobs: gradle-version: 8.5 - name: Build with Gradle id: build - run: gradle -PgithubReleaseTag=vtesttag buildReleaseArtifacts + run: gradle -PgithubReleaseTag=${{ github.event.release.tag_name }} buildReleaseArtifacts - name: Release uses: softprops/action-gh-release@v2 with: diff --git a/build.gradle.kts b/build.gradle.kts index 41b6b06..5bbe9ed 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -41,16 +41,13 @@ group = "com.myDomain" // - MINOR: Increases when you add new features that are backward-compatible. // - PATCH: Increases when you make backward-compatible bug fixes. // You can update these numbers as you release new versions of your library. + // the following conditional allows for the version to be overwritten by a Github release // via the release workflow, which defines a property named "githubReleaseTag" version = if (project.hasProperty("githubReleaseTag")) { - // remove leading "v" from tag if present - if (project.property("githubReleaseTag").toString().substring(0,1) == "v") { - project.property("githubReleaseTag").toString().drop(1) - } else { - project.property("githubReleaseTag").toString() - } + // remove leading "v" from tag (the leading "v" is required for the release workflow to trigger) + project.property("githubReleaseTag").toString().drop(1) } else { "1.0.0" diff --git a/docs/develop.md b/docs/develop.md index a114c10..9908f46 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -65,7 +65,19 @@ those sections for [resolving dependencies](#resolving-dependencies). notation. For example, if your website is "myDomain.com", your group ID would be "com.myDomain". This group id should match the group id discussed in section [Developing the library](#developing-the-library). -3. **Define the `version` of your library in `build.gradle.kts`.** This value will also be +3. The `sketchbookLocation` is determined programmatically by your operation system, and is + where your Processing `sketchbook` folder is. This folder contains your installed libraries. + It is needed if you: + + 1. wish to copy the library to the Processing sketchbook, which installs the library locally + 2. have Processing library dependencies + + This variable is in the editable section, in case the location determined is incorrect. A + symptom of an incorrect `sketchbookLocation` is that your library does not show up as a + contributed library Processing, after being installed. Please look at our + [troubleshooting guide](troubleshooting.md) if you suspect this is the case. + +4. **Define the `version` of your library in `build.gradle.kts`.** This value will also be included in the release artifact `library.properties`. The version of your library usually follows semantic versioning (semver), which uses three numbers separated by dots: "MAJOR.MINOR.PATCH" (e.g., "1.0.0"). @@ -76,18 +88,10 @@ those sections for [resolving dependencies](#resolving-dependencies). You will update these numbers as you release new versions of your library. -4. The `sketchbookLocation` is determined programmatically by your operation system, and is - where your Processing `sketchbook` folder is. This folder contains your installed libraries. - It is needed if you: +!!! Note + If you [release your library on Github](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository), + the prettyVersion field in your release artifacts will reflect your release tag instead of the `version` defined in `build.gradle.kts`, as a helpful automation. - 1. wish to copy the library to the Processing sketchbook, which installs the library locally - 2. have Processing library dependencies - - This variable is in the editable section, in case the location determined is incorrect. A - symptom of an incorrect `sketchbookLocation` is that your library does not show up as a - contributed library Processing, after being installed. Please look at our - [troubleshooting guide](troubleshooting.md) if you suspect this is the case. - ## Creating examples Examples help users understand your library’s functionality, it is recommended that you include several clear and well-commented samples sketches in the `examples` folder. diff --git a/docs/release.md b/docs/release.md index b6ce6f6..d089296 100644 --- a/docs/release.md +++ b/docs/release.md @@ -31,17 +31,25 @@ Any time you want to update the documentation, edit your `.md` files and `mkdocs If you prefer not to use the built-in workflow with GitHub Pages and Material for MkDocs, you are free to use another static site generator or hosting service. Note that it’s important that the site remains online, as it serves as a reference for users of your library. ## Releasing on Github -Releasing your library on GitHub allows users to access known-working versions of your library. Unlike the repository itself, which may contain ongoing development or experimental features, releases provide specific versions of your library that are ready for use. Here is how you can make a new release using this template: +[Releasing your library on GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) +allows users to access known-working versions of your library. Unlike the repository itself, which may contain ongoing development or experimental features, releases provide specific versions of your library that are ready for use. Here is how you can make a new release using this template: 1. In your repository, click on **Releases**. 2. Click **Draft a new release** to start. -3. Click on **Choose a tag** a tag starting with "v" (e.g., `v1.0.0`). Make sure it matches the version set in your `release.properties` file. +3. Click on **Choose a tag** and type a tag **starting with "v"** (e.g., `v1.0.0`). 4. Select the branch you want to use for this release (e.g., `main`). 5. Add a title and description for the release, highlighting key updates or changes. 6. Click on **Publish release**. This will trigger the GitHub workflow (`.github/workflows/release.yml`), which automatically create release artifacts—`*.txt`, `*.zip`, `*.pdex` files—and add them to the release. +!!! Important + The release workflow will only trigger if the release tag starts with `v`. + +!!! Important + The release tag created on Github will be propagated to the release artifacts. + Specifically the tag, without the leading `v`, will be used for the `prettyVersion` in the txt file and `library.properties` file in the zip. This overwrites the value input for `version` in the `build.gradle.kts` file. + !!! Note By default, GitHub will also include compressed versions of your source code (e.g., `Source code (zip)` and `Source code (tar.gz)`). From a9b0e6d979a1f833883d6157f07d9b3a97a04ff1 Mon Sep 17 00:00:00 2001 From: Claudine Date: Mon, 24 Mar 2025 16:49:50 +0000 Subject: [PATCH 4/4] parse full tag --- .github/workflows/release.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b1e73c2..325a18f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -10,7 +10,7 @@ jobs: permissions: write-all runs-on: ubuntu-latest env: - TAG_NAME: ${{ github.event.inputs.tag }} + FULL_RELEASE_TAG: ${{ github.ref || format('{0}{1}', 'refs/tags/', github.event.release.tag_name) }} steps: - name: Checkout sources uses: actions/checkout@v4 @@ -23,9 +23,13 @@ jobs: uses: gradle/actions/setup-gradle@v3 with: gradle-version: 8.5 + - name: Extract tag name + run: | + echo "RELEASE_TAG=${FULL_RELEASE_TAG:10}" + echo "RELEASE_TAG=${FULL_RELEASE_TAG:10}" >> $GITHUB_ENV - name: Build with Gradle id: build - run: gradle -PgithubReleaseTag=${{ github.event.release.tag_name }} buildReleaseArtifacts + run: gradle -PgithubReleaseTag=${{ env.RELEASE_TAG }} buildReleaseArtifacts - name: Release uses: softprops/action-gh-release@v2 with: