diff --git a/build.gradle.kts b/build.gradle.kts index c9afb2f..1d8cd9b 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -18,6 +18,21 @@ java { } } +// read in user-defined properties in release.properties file +// most of these properties will be saved to the library.properties file, a required file in the release +// using task writeLibraryProperties +val libraryProperties = Properties().apply { + load(rootProject.file("release.properties").inputStream()) +} + +// 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 { + libraryProperties.getProperty("prettyVersion") +} //========================== // USER BUILD CONFIGURATIONS @@ -35,24 +50,6 @@ val libName = "myLibrary" // Replace "com.myDomain" with your own domain or organization name. group = "com.myDomain" -// The version of your library. It usually follows semantic versioning (semver), -// which uses three numbers separated by dots: "MAJOR.MINOR.PATCH" (e.g., "1.0.0"). -// - MAJOR: Increases when you make incompatible changes. -// - 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 (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: // 1. wish to copy the library to the Processing sketchbook, which installs the library locally @@ -149,13 +146,6 @@ val releaseRoot = "$rootDir/release" val releaseName = libName val releaseDirectory = "$releaseRoot/$releaseName" -// read in user-defined properties in release.properties file -// to be saved in library.properties file, a required file in the release -// using task writeLibraryProperties -val libraryProperties = Properties().apply { - load(rootProject.file("release.properties").inputStream()) -} - tasks.register("writeLibraryProperties") { group = "processing" destinationFile = project.file("library.properties") diff --git a/docs/develop.md b/docs/develop.md index 9908f46..17b7426 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -77,20 +77,6 @@ those sections for [resolving dependencies](#resolving-dependencies). 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"). - - - MAJOR: Increases when you make incompatible changes. - - MINOR: Increases when you add new features that are backward-compatible. - - PATCH: Increases when you make backward-compatible bug fixes. - - You will update these numbers as you release new versions of your library. - -!!! 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. ## 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. @@ -99,16 +85,13 @@ Examples help users understand your library’s functionality, it is recommended The example sketch included in this template outputs the image shown on the home page. ## Creating the release artifacts -If you've already gone through the [Getting started](getting-started.md#first-steps) guide, you will have -already run Gradle tasks, and edited the `release.properties` file. -1. Fill in the file `release.properties` with information for your library. This information will be - used by Gradle to create the `library.properties` file, which is one of the required release - artifacts, used by the website and Contribution Manager to describe your library. In the file itself, - There are comments to guide you. To create just the `library.properties` file without building the +1. Fill in the file `release.properties` with information for your library. In the file itself, + There are comments to guide you. This information will be used by Gradle to create the + `library.properties` file, which is one of the required release artifacts, used by the website + and Contribution Manager to describe your library. To create just the `library.properties` file without building the library, toggle `Tasks` > `processing` and double click `writeLibraryProperties`. This task will - copy all the values in `release.properties`, and also include the `version` in your `build.gradle.kts` - file as `prettyVersion`. + copy all the values in `release.properties`. 2. **To build the library and create the release artifacts, run the Gradle task `buildReleaseArtifacts`.** This task will create a `release` folder with needed artifacts. To do this, go to the Gradle menu (elephant), toggle `Tasks` > `processing` and double click `buildReleaseArtifacts`. This task @@ -124,6 +107,13 @@ already run Gradle tasks, and edited the `release.properties` file. `deployToProcessingSketchbook`, which will create the release artifacts, and copy them into the sketchbook folder. + +!!! Note +If you [release your library on Github](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository), +your release tag will be used for the value of the `prettyVersion` field, overwriting the value for `prettyVersion` +defined in `release.properties`, as a helpful automation. + + ## Additional Documentation See the following guides for more details: diff --git a/docs/release.md b/docs/release.md index d089296..5afd6d4 100644 --- a/docs/release.md +++ b/docs/release.md @@ -48,7 +48,7 @@ This will trigger the GitHub workflow (`.github/workflows/release.yml`), which a !!! 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. + 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 `prettyVersion` in the `release.properties` file. !!! Note By default, GitHub will also include compressed versions of your source code (e.g., `Source code (zip)` and `Source code (tar.gz)`). diff --git a/release.properties b/release.properties index 53c95af..04324ab 100644 --- a/release.properties +++ b/release.properties @@ -10,6 +10,18 @@ name=A Template Example Library # releases you've had. NOTE: This must be parsable as an int! version=1 +# The version of your library. It usually follows semantic versioning (semver), +# which uses three numbers separated by dots: "MAJOR.MINOR.PATCH" (e.g., "1.0.0"). +# - MAJOR: Increases when you make incompatible changes. +# - 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. +# +# Note: The prettyVersion value defined here can be overwritten by a GitHub release tag. +# If a release tag is present, the numeric part of the tag will be used as the version number. +# See docs/release.md for more details. +prettyVersion = 1.0.0 + # List of authors. Links can be provided using the syntax [author name](url). authors=[Your Name](https://myDomain.com)