Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xenoterracide/gradle-semver
https://github.com/xenoterracide/gradle-semver
auto-updates
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/xenoterracide/gradle-semver
- Owner: xenoterracide
- License: apache-2.0
- Created: 2024-02-15T21:22:57.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-10-25T06:40:43.000Z (3 months ago)
- Last Synced: 2024-10-25T14:24:37.104Z (3 months ago)
- Topics: auto-updates
- Language: Java
- Size: 534 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# README
A semantic versioning plugin that derives the version from git tags and commits and is configuration cache safe.
_Plugin ID_: `"com.xenoterracide.gradle.semver"`
_Version_: `0.12.+`
## Usage
```kt
plugins {
id("com.xenoterracide.gradle.semver")
}
version = semver.provider().get()
```
This is the simplest way to get your semver, but I don't recommend it because [Gradle isn't lazy with anything related to publishing](https://github.com/gradle/gradle/issues/29342). Even when it becomes lazy I doubt it'll be as lazy as you want. So I do the following, and then only set `IS_PUBLISHING` in my publishing build in CI. This avoids constant configuration cache busting as well as ensuring that IO is kept to a minimum.
```kt
import org.semver4j.Semver
version = providers.environmentVariable("IS_PUBLISHING")
.map { semver.provider().get() }
.orElse(Semver("0.0.0")).get()
```
This plugin expects that you will `git tag` in the format of `v0.1.1` and with only one number on prerelease versions,
e.g. `v0.1.1-rc.1`. It also expects that you will use annotated tags.
```kt
// given the last tag was v0.1.0 and you have a commit distance == 1 you'll get something like
logger.quiet("semver " + semver.provider().get() // 0.1.1-alpha.0.1+g3aae11e
// other available outputs
logger.quiet("branch:" + gitMetadata.branch )
logger.quiet("commit:" + gitMetadata.commit)
logger.quiet("commitShort:" + gitMetadata.commitShort)
logger.quiet("latestTag:" + gitMetadata.latestTag)
logger.quiet("describe:" + gitMetadata.describe)
logger.quiet("commitDistance:" + gitMetadata.commitDistance)
logger.quiet("status:" + gitMetadata.status)
```
if you want you can expose whether your tree is dirty or not.
```kt
semver {
checkDirty.set(true)
}
logger.quiet("semver " + semver.provider().get() // 0.1.1-alpha.0.1+g3aae11e.dirty
```
The plugin exposes a `Semver`. See [Semver4J](https://javadoc.io/doc/org.semver4j/semver4j/latest/index.html).
## FAQ
### Shallow Clones
```
shallow clone detected! git only has {} commits
```
Shallow clones will not work properly with calculating the distance and thus you must not use them. The usual reason for doing a shallow clone is that repositories can grow quiet large, and it can be quite slow to download a 100Mb repository. What most people don't realize is that git is lazy and will fetch blobs as it needs them for a checkout if you do things correctly. `git add remote ` and then doing `git fetch --all --filter blob:none` followed by an operation like `git checkout ` will not retrieve any files until you do the git checkout but it will have your full history. This will achieve the correct behavior on github.
```yml
- uses: actions/checkout@v4
with:
ref: ${{ github.event.workflow_run.head_branch}}
filter: "blob:none"
fetch-depth: 0
```
### Annotated Tags
- [GitHub does not checkout annotated tags properly](https://github.com/actions/checkout/issues/882)
You can use this snippet or another workaround documented on the issue
```yml
- uses: actions/checkout@v4
with:
ref: ${{ github.ref }}
```
## Goals
Provide Semantic versioning for Maven publishing with Gradle.
_Future_: Provide a way to determine what the next version should be using your projects ABI.
## Contributing
### Languages
[asdf](https://asdf-vm.com) is suggested, you can use whatever you'd like to get
- Java 11+
- NodeJs
add a way to export these to your `PATH` in your `~/.profile`
### Build Tools
- [Gradle](https://docs.gradle.org/current/userguide/command_line_interface.html)
- [NPM](https://docs.npmjs.com/about-npm)
Run `npm ci && ./gradlew dependencies` to install dependencies.
#### Fetching Dependencies
In order to get snapshots of dependencies, you must have a GitHub token in your `~/.gradle/gradle.properties` file. This
file should look like:
```properties
ghUsername =
ghPassword =
```
You should generate your PAT
as [Github Documents here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry#authenticating-to-github-packages).
> a personal access token (classic) with at least read:packages scope to install packages associated with other private
> repositories (which GITHUB_TOKEN can't access).
Then run.
Run `npm ci && ./gradlew dependencies` to install dependencies.
### Committing
Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
### Releasing
```sh
npm run release --semver="0.10.0"
```
## License
- Java: [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/)
- Gradle Kotlin and Config Files: [MIT](https://choosealicense.com/licenses/mit/)
- Documentation including Javadoc: [CC BY 4.0](https://choosealicense.com/licenses/cc-by-4.0/)
© Copyright 2024 Caleb Cushing.