GitHub release tag propagated to artifacts (#82)

* test build gradle with workflow

* test for v

* simplify, and docs

* parse full tag

Author: mingness

.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 buildReleaseArtifacts
+        run: gradle -PgithubReleaseTag=${{ env.RELEASE_TAG }} buildReleaseArtifacts
       - name: Release
         uses: softprops/action-gh-release@v2
         with:

build.gradle.kts

@@ -41,7 +41,17 @@ 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 "githubReleaseTag"
+
+version = if (project.hasProperty("githubReleaseTag")) {
+    // 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"
+}
 
 // The location of your sketchbook folder. The sketchbook folder holds your installed
 // libraries, tools, and modes. It is needed if you:

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.
 

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)`).