gradle-semantic-release-example

About

An example project that is automatically deployed

Built With

JVM Kotlin Gradle

Getting Started

Prerequisites

• nvm
• docker
• sdkman

Development

nvm use # need for configure nodejs
sdk env # need for configure jvm
npm i # need for install git hooks

Installation

TODO

Applied practices

Issue automation

Для организации автоматического создания веток на основе правил из issue используется create-issue-branch.

При задании assignee для issue автоматически создаётся ветка и pull request на основе правил из issue-branch.yml.

При создании pull request в тело добавляет текст формата closes #XX, что приводит при закрытии pull request к автоматическому закрытию issue. Если данное поведение избыточно, то до закрытия pull request следует удалить данный фрагмент из его тела.

Github labels

Для синхронизации labels используется micnncim/action-label-syncer, а для проверки labels в pull requests - jesusvasquez333/verify-pr-label-action.

Для описания labels используется файл labels.yml.

Conventional commits

Для проверки сообщений коммитов на соответствие методологии Conventional Commits на уровне публикации коммитов используется husky+commitlint, а на уровне CI wagoid/commitlint-github-action.

Конфигурация commitlint находится в commitlint.config.js.

Automated dependency updates

Для автоматического обновления зависимостей используется renovate. Это приложение автоматически отслеживает все манифесты в приложении, которые содержат списки зависимостей и обновляет их версии.

Конфигурационный файл для renovate находится в renovate.json и содержит следующие директивы:

• использовать Conventional Commits в текстах коммитов и заголовках pull requests(build(deps): ...)
• добавлять label dependencies, указывать assignee и reviewer на основе CODEOWNERS в pull requests
• использовать ветку develop как базовую
• Использовать Dependency Dashboard Approval workflow для обновления всех зависимостей

Automated Gitflow pull requests

Для автоматического создания pull requests между главной веткой(master), ветка разработки(develop) и ветками выпуска(rc,release) используется gitflow-action.

В его обязанности входит:

• при появлении ветки rc, создание pull request rc->master
• при изменении ветки master, создание pull request master->develop

CI test section

Тестирование в контексте CI происходит следующим образом:

• задача на тестирование запускается для PR и перед сборкой артефакта
• перед запуском тестов выполняется:
  • sdkman/sdkman-action - установка jdk
  • gradle/actions/setup-gradle - установка gradle wrapper и кеширование зависимостей
• выполняется ./gradlew build, которые включает в себя тесты
• далее запускается EnricoMi/publish-unit-test-result-action - публикация результатов выполнения тестов в github actions и pull request

Semantic version publication

Для организации версионирования на основе semantic version используется semantic-release. Конфигурационный файл для semantic-release находится в release.config.js и содержит следующие плагины:

• semantic-release/commit-analyzer - определяет соответствие Conventional Commits scopes с уровнем публикуемого релиза.
• semantic-release/release-notes-generator - генерирует release notes на основе Conventional Commits
• semantic-release/github - публикует релиз в github и комментирует pull request и issues связанные с релизом
• semantic-release/exec - реализует кастомные этапы, в том числе публикацию в docker hub и выведение переменных из процесса semantic-release для использования в других этапах github actions
• semantic-release/changelog - генерирует CHANGELOG.md для стабильных релизов, исключающих prerelease
• semantic-release/git - выполняет фиксацию изменений в репозитории в процессе выполнения выкатки релиза. Включает изменения CHANGELOG.md.

Для поддержки semantic version на уровне gradle используется плагин git-version. Для сборки рабочей версии артефакта следует github action указывает параметр -Pversion. Для сборок не предназначенных для публикации или не являющихся стабильными git-version рассчитывает версию на основе ветки и hash-commit. В случае если имеется незафиксированные изменения, то добавляется суффикс +SNAPSHOT.

Docker hub publication

Для публикации образов docker используются возможности Spring Boot Gradle Plugin. Был кастомизирован build.gradle.kts в области задачи bootBuildImage. На основе параметров dockerHubUsername и dockerHubPassword определяется имя образа и необходимость его публикации в docker hub. Параметр withLatest используется для создания/публикации дополнительного тега docker image - latest.

Настройка лицензирования в проекте

Указание лицензии в репозитории

Добавить файл LICENSE в корень репозитория.

Указание лицензии в исходных файлах

Для указания лицензий в исходных файлах используется gradle-plugin spotless.

При первоначальном генерировании заголовков следует использовать команду ./gradlew spotlessApply -PspotlessSetLicenseHeaderYearsFromGitHistory=true

Для обновления заголовков следует использовать команду ./gradlew spotlessApply.

Для проверки заголовков следует использовать команду ./gradlew spotlessCheck.

Указание лицензии в jar-артефакте

Для удобства использования параметров в gradle.build используется плагин gradle-extensions-plugin.

Список стандартных заголовков jar-манифеста представлен в:

• https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#Manifest_Specification
• https://docs.osgi.org/reference/bundle-headers.html

Для объявления контактной информации используется плагин com.netflix.nebula.contacts. Смысл использования в том что он интегрируется с другими плагинами com.netflix.nebula.

Для наполнения заголовков jar-манифеста используется набор плагинов com.netflix.nebula.info:

• nebula.info-broker - база для использования всех остальных плагинов
• nebula.info-basic - собирает базовую информацию сборки gradle
• nebula.info-java - собирает информацию о версиях jvm
• nebula.info-ci - собирает информацию сборки ci/cd
• nebula.info-scm - собирает информацию git
• nebula.info-jar - добавляет собранные атрибуты в jar-манифест

Информация об авторе и лицензии проставляется через добавление следующей логики в Jar-таску:

tasks.configureEach<Jar> {
    // ...
    manifest {
        attributes["Bundle-License"] = license
        attributes["Implementation-Vendor"] = author.asString()
    }
}

Для агрегации, проверки и указывания лицензий используемых зависимостей, в случае если происходит сборка fat-jar используются gradle-плагины:

• license-gather
  • анализирует лицензии зависимостей(gatherLicense)
  • проверяет их согласно правилам(verifyLicenses)
• stage-vote-release
  • плагин для публикации артефакта. Для сборки fat-jar выключен
  • генерирует расширенный файл лицензии(renderLicense)
  • добавляет расширенный файл лицензии и файлы лицензий зависимостей в jar-артефакт(licenseFiles)

Для того чтобы в jar-артефакт добавлялись файлы лицензий так-же необходимо в Jar-тасках прописать логику копирования:

tasks.configureEach<Jar> {
    // ...
    into("META-INF") {
        dependencyLicenses(licenseFiles)
    }
}

Указание лицензии в docker-артефакте

Для указания лицензии и прочих атрибутов в docker-образе будет использоваться OCI-specified labels.

Так как Spring Boot Gradle Plugin по умолчанию для сборки docker-image через Paketo Buildpacks использует сборщик paketobuildpacks/builder-jammy-base, который в свою очередь использует paketo-buildpacks/java, который в свою очередь использует paketo-buildpacks/image-labels, то для того чтобы указать необходимые labels достаточно в переменные окружения добавить значения описанные в документации к последнему сборщику.

Security

gradle-semantic-release-example is provided "as is" without any warranty. Use at your own risk.

License

This project is licensed under the Apache Software License 2.0.

See LICENSE for more information.

External resources

• husky
• commitlint
• wagoid/commitlint-github-action
• micnncim/action-label-syncer
• jesusvasquez333/verify-pr-label-action
• Conventional Commits
• Mermaid
• semantic-release