{"id":28304392,"url":"https://github.com/harmonysoft-tech/gradle-release-paperwork","last_synced_at":"2026-02-13T05:46:37.899Z","repository":{"id":146757087,"uuid":"528250718","full_name":"harmonysoft-tech/gradle-release-paperwork","owner":"harmonysoft-tech","description":"Takes care of automatic version update in gradle projects and populating change log","archived":false,"fork":false,"pushed_at":"2024-12-24T12:55:18.000Z","size":123,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-24T00:12:56.943Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harmonysoft-tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-24T03:27:29.000Z","updated_at":"2025-03-27T03:23:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"7606a84f-7ef2-4696-bf54-e14a251caba4","html_url":"https://github.com/harmonysoft-tech/gradle-release-paperwork","commit_stats":null,"previous_names":["harmonhsoft-tech/gradle-release-paperwork","harmonysoft-tech/gradle-release-paperwork"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/harmonysoft-tech/gradle-release-paperwork","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmonysoft-tech%2Fgradle-release-paperwork","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmonysoft-tech%2Fgradle-release-paperwork/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmonysoft-tech%2Fgradle-release-paperwork/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmonysoft-tech%2Fgradle-release-paperwork/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harmonysoft-tech","download_url":"https://codeload.github.com/harmonysoft-tech/gradle-release-paperwork/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harmonysoft-tech%2Fgradle-release-paperwork/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29397203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T04:26:15.637Z","status":"ssl_error","status_checked_at":"2026-02-13T04:16:29.732Z","response_time":78,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-24T00:12:56.969Z","updated_at":"2026-02-13T05:46:37.895Z","avatar_url":"https://github.com/harmonysoft-tech.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gradle-release-paperwork\n\n## Overview\n\nTakes care of automatic version update in git based gradle projects and populates release notes.\n\nExample:\n  * current project's *build.gradle.kts* has `version = \"3.5.1\"`\n  * last released version in *RELEASE_NOTES.md* is the same (`3.5.1`)\n  * the plugin automatically applies version `3.6.0` to the *build.gradle.kts*\n  * there were two non-merge git commits after `3.5.1`, they had commit messages `message1` and `message2`\n  * the plugin automatically populates *RELEASE_NOTES.md* by the text below:\n\n    ```\n    ## v3.6.1 released on 19 Oct 2022 UTC\n    * 8dadf86f930b189d5e16457a309e41c62da5e949 - message1\n    * 6382b31bc781339d884708196fb87be7e31bb472 - message2\n    ```\n\n  * the plugin commits the changes in *build.gradle.kts* and *RELEASE_NOTES.md* into git\n  * the plugin creates git tag `v3.6.0` from the current sources\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Table of Contents](#table-of-contents)\n3. [How to Use](#how-to-use)\n4. [Configuration](#configuration)\n    * [Version File Location](#version-file-location)\n    * [Version Regex](#version-regex)\n    * [Release Notes File Location](#release-notes-file-location)\n    * [Additional Release Info](#additional-release-info)\n    * [Change Description](#change-description)\n    * [Changes Limit](#changes-limit)\n    * [Define Tag Pattern](#define-tag-pattern)\n\n## How to Use\n\nThe plugin adds `release-paperwork` task to the root project. It does the necessary actions, namely:\n1. Collect unreleased changes (git commits)\n2. Update current project version if necessary\n3. Populate release notes by target commits info\n\nBy default, the plugin assumes that [semver](https://semver.org/) is used by the host project and it increments 'minor' version on release. However, sometimes we want to explicitly define a version to use, for example increment a 'patch' version on bugfix release. The plugin uses currently defined version if it's not the same as the last released version. Example:\n\n1. Version `1.0.0` was released\n2. New bug fix commit is made\n3. Project version is explicitly set as `1.0.1`\n4. `release-paperwork` task is called\n5. Release notes are populated by the bug fix commit info for version `1.0.1`. Project version is not changed\n\n## Configuration\n\nThe plugin uses default settings if no explicit configuration is defined, they should suit the majority of projects. However, it also offers fine-grained configuration for all processing aspects\n\n### Version File Location\n\nNormally project version is defined in root `build.gradle`/`build.gradle.kts`, but it might be set in other place instead, like `buildSrc`, `gradle.properties`, etc. We can instruct the plugin to use any project file as a version info holder. Usually this property goes with [Version Regex](#version-regex) setup:\n\n```\nreleasePaperwork {\n    projectVersionFile.set(\"gradle.properties\")\n    projectVersionRegex.set(\"project.version\\\\s*=\\\\s*(.+)\")\n}\n```\n\n*Note: file location is relative to root project's directory*\n\n### Version Regex\n\nTarget use-case is described in [Version File Location](#version-file-location), this property allows to define custom regex for current project version extraction from the version file. Default value is `version\\s*=\\s*['\"]([^'\"]+)` to cover cases like `version = \"1.0.0\"`\n\n**Note**: []\n\n### Release Notes File Location\n\nBy default, the plugin writes release notes to file `RELEASE_NOTES.md` located at the project. However, it's possible to define custom file to use for that via `releaseNotesFile` property (its location is relative to root project's directory):\n\n```\nreleasePaperwork {\n    releaseNotesFile.set(\"releases.txt\")\n}\n```\n\n### Additional Release Info\n\nEvery new version is stated in release notes file as below:\n\n```\n## vA.B.C released on 19 Oct 2022 UTC\n  * \u003ccommit-hash1\u003e feature1\n  * ...\n  * \u003ccommit-hashN\u003e featureN\n```\n\nIt's possible to add additional information to the release info via `additionalReleaseDescription` property. It should be a no-args lambda which produces text. The produced non-empty text is added after base release info:\n\n```\nreleasePaperwork {\n    additionalReleaseDescription.set {\n        \", build id ${System.getenv(\"CI_BUILD_ID\")}\"\n    }\n}\n```\n\nSuch setup would make release notes look as below:\n\n```\n## vA.B.C released on 19 Oct 2022 UTC, build id XYZ\n  * \u003ccommit-hash1\u003e feature1\n  * ...\n  * \u003ccommit-hashN\u003e featureN\n```\n\n### Change Description\n\nEvery new version is stated in release notes file as below:\n\n```\n## vA.B.C released on 19 Oct 2022 UTC\n  * \u003ccommit-hash1\u003e feature1\n  * ...\n  * \u003ccommit-hashN\u003e featureN\n```\n\n`featureN` here is just commit message. It's possible to customize its representation in the release notes file via `changeDescription` property - it's a lambda which receives default description (commit message) and returns description to use. If returned description is null or an empty string, the whole commit is excluded from release notes. This feature can be used to exclude merge commits. Consider, for example, the following git log (spring boot project):\n\n```\ncommit 8dadf86f930b189d5e16457a309e41c62da5e949\nMerge: 07dd388b58 fcaac2b343\nAuthor: Phillip Webb \u003cpwebb@vmware.com\u003e\nDate:   Tue Oct 18 17:15:03 2022 -0700\n\n    Merge branch '2.7.x'\n\n    Closes gh-32778\n```\n\nComplete commit message is used as a feature description by default, so, it would result in the following release notes:\n\n```\nvA.B.C released on 19 Oct 2022 UTC\n  * 8dadf86f930b189d5e16457a309e41c62da5e949 Merge branch '2.7.x' Closes gh-32778\n```\n\nWe can turn this into something more convenient then:\n\n```\nreleasePaperwork {\n    val mergeRegex = \"[Mm]erge branch \\\\S+\".toRegex()\n    val ticketRegex = \"gh-(\\\\d+)\".toRegex()\n    changeDescription.set { commitMessage -\u003e\n        val withDroppedMergeInfo = mergeRegex.replace(commitMessage, \"\").trim()\n        ticketRegex.replace(withDroppedMergeInfo) { match -\u003e\n            buildString {\n                append(\"[\")\n                append(match.groupValues[1])\n                append(\"](https://github.com/spring-projects/spring-boot/issues/\")\n                append(match.groupValues[1])\n                append(\")\")\n            }\n        }\n    }\n}\n```\n\nIt results in release notes content as below:\n\n```\n## vA.B.C released on 19 Oct 2022 UTC\n  * 8dadf86f930b189d5e16457a309e41c62da5e949 Closes [32778](https://github.com/spring-projects/spring-boot/issues/32778)\n```\n\n### Changes Limit\n\nThere might be quite a few commits since the last released version (for example, if we apply the plugin to a project with rich changes history). It might not be worth to list all of them into release notes for particular version. By default, the plugin includes only the last 20 commits per version. That can be adjusted via `maxChangesPerRelease` property. Non-positive value means that there is no limit:\n\n```\nreleasePaperwork {\n    maxChangesPerRelease.set(50)\n}\n```\n\n### Define Tag Pattern\n\nThere is a specific case where we want created tag name to be customized. It can be done by set the `tagPattern` as below:\n\n```\nreleasePaperwork {\n   tagPattern.set(\"v%s\")\n}\n```\n\nWhich will create a tag with this format:\n\n```v1.0.0```\n\nDo remember that the character `%s` must be provided as the place for the version. If `tagPattern` does not defined, default pattern\nwill be `v%s` which will create a tag with this format:\n\n```v1.0.0```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharmonysoft-tech%2Fgradle-release-paperwork","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharmonysoft-tech%2Fgradle-release-paperwork","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharmonysoft-tech%2Fgradle-release-paperwork/lists"}