Skip to content

Latest commit

 

History

History
106 lines (80 loc) · 5.8 KB

release-drafter.adoc

File metadata and controls

106 lines (80 loc) · 5.8 KB
Raw

Release Drafter

Release Drafter is a tool and GitHub app which helps to automate the management of releases notes. This tool generates changelog drafts using pull request metadata (commit headers, links, etc.) and then suggest a changelog draft in GitHub Releases. Jenkins project offers some tools which simplify usage of Release Drafter in the https://github.com/jenkinsci/ organization. This page provides information about how to use it.

Table of Contents

Usage

Release drafter can be used as a GitHub Application or as a GitHub action. The recommended approach is to use the GitHub Action as the GitHub App is deprecated and won’t receive new features anymore. Also, the Application does not produce logs which would be available to plugin maintainers, and hence it might be difficult to troubleshoot errors if they occur.

Configuring Release Drafter

Release drafter needs to be configured in .github/release-drafter.yml in the default branch of your repository. Jenkins project provides a Global Configuration file, so a minimal configuration looks like this one:

_extends: .github
#FIXME: change role-strategy to your component
tag-template: role-strategy-$NEXT_MINOR_VERSION

All global settings can be overridden in repositories. Or you can write your own configuration from scratch if needed. See the Release Drafter Documentation for guidelines. If a change you need is a common use-case for Jenkins, it is recommended to submit a pull request to the Global Configuration file

Global configuration notes

There are some considerations about the default configuration:

  • Default tag template (tag-template) always needs to be configured by the user, because Maven Release Plugin in Plugin POM uses the ${artifactId}-${version} tag format by default. It needs to be overridden in repos (see the linked examples)

  • Jenkins plugins use different versioning format. Release Drafter defaults to semver, but the majority of Jenkins plugins use the two-digit version number. We use it as a default in the global configuration, but it can be overridden (e.g. version-template: $MAJOR.$MINOR.$PATCH)

  • Next version number will be used by default as a next release name. Another naming template can be defined by a name-template property, e.g. name-template: My Plugin v$NEXT_PATCH_VERSION

  • There are automatic replacers for Jenkins Jira ticket IDs, CVE IDs, and some acronyms. Current replacer regexps target the common [JENKINS-1234] - Change description pull request patterns with some deviations (missing brackets, spacing and so on)

Releasing a component via CD

  • If you have automated plugin releases configured, you can skip the paragraph below. CD handles manual releases differently.

Manually releasing a component with Release Drafter

  1. Make sure that all pull requests in the release are properly labeled. See the Global Configuration file for available labels

  2. Release a component as usual (e.g. using Maven Release Plugin for Jenkins plugins)

  3. Go to ${YOUR_REPO}/releases and click "Edit" on the draft release.

  4. Edit the tag, point it to a tag or a release commit created by the common release flow

    • Tags represent a text field with auto-completion. Tag names can be also copy-pasted from ${YOUR_REPO}/tags

    • Recent commits can be selected from a dropdown

    • Make sure you see the text Existing tag (see demo)

  5. Edit the release name, if needed

  6. Review and copy-edit the changelog

    • First release draft will likely contain all history from the beginning of the repository, you will need to remove entries corresponding to PRs included in prior releases. If all new PRs are categorized, just delete everything before the first header.

    • Release drafter is designed to add one entry per pull request. If a pull request includes multiple changes to be noted, manual editing will be needed

  7. Click the Publish button

Watch this demo of steps 3–7.

Jenkins Online Meetup Recording

On Nov 22, 2019, we have recorded a Jenkins Online Meetup with the overview of Release Drafter in Jenkins:

Examples

Below you can find examples of changelogs with enabled Release Drafter. Configurations can be found in ".github/release-drafter.yml" for every repo.