~aperezdc/webkit-releng-toolbelt

Assorted tools for WebKit {WPE,GTK} release management
ebaae169 — Adrian Perez de Castro 9 months ago
defaults.yml: Quote Markdown blog post title
ebdb9517 — Adrian Perez de Castro 9 months ago
generate: Support a -v/--verbose command line flag
93b71c65 — Adrian Perez de Castro 9 months ago
Support a new %{stability} template variable

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~aperezdc/webkit-releng-toolbelt
read/write
git@git.sr.ht:~aperezdc/webkit-releng-toolbelt

You can also use your local clone with git send-email.

WebKit Release Engineering Toolbelt

This repository contains tools used mainly by people involved in producing releases for WebKitGTK and WPE WebKit.

Installation

Python version 3.5 or newer is needed. The simplest way of installing the tools is cloning the repository and installing along with the needed dependencies in a virtualenv using pip:

git clone https://git.sr.ht/~aperezdc/webkit-releng-toolbelt
cd webkit-releng-toolbelt
virtualenv -p "$(which python3)" ./myenv
. ./myenv/bin/activate
pip install -e .

Now running wkrel help command should produce a list of available subcommands.

Configuration

The tool is configured using a set of YAML text files placed in a “configuration directory” — which can be passed to any command which accepts the --config-dir/-C command line option:

  • Each .yml file contains the configuration for a “release package” tarball.
  • A file named defauls.yml contains default configuration values which are used for those values not overriden or specified in a release package tarball.

For the sake of convenience, when a configuration directory not indicated, the conf/ subdirectory of the source distribution is used by default.

Additionally, a wkrel/user.yml file can be used to specify configuration values which override those loaded from the configuration directory. This allows each person using the tool to easily indicate certain preferences like their e-mail address or PGP key used for signing packages. This user configuration file will be searched using the XDG Base Directory Specification, which most of the time means it will be located at ~/.config/wkrel/user.yml.

Package Definition

The YAML file for each package may contain the following top level elements:

Element Variable Contents
package %{package} Descriptive name of the package.
pattern %{pattern} Pattern for release files, the % character matching the package version.
gpgkey %{gpgkey} PGP key identifier used to sign files. (Optional.)
changelog %{changelog} Path to a NEWS-like file inside the tarball. (Optional.)
variables %{variables.*} Mapping of strings with additional variables. (Optional.)
email %{email.*} Mapping for an e-mail configuration. (Optional. Details below.)
files %{files.*} Mapping for generated files configuration. (Optional. Details below.)

The following is a minimal example of a self-contained package definition:

# This only makes “wkrel” aware of package files matching the pattern.
package: Foo Library
pattern: libfoo-%.tar.xz

A more realistic example, setting the files section to allow generating a .sums file with the package checksums:

package: Bar Library
pattern: libbar-%.tar.xz
files:
  sums: |
    %{tar.filename} (%{tar.humansize}):
      sha256: %{tar.sha256sum}

The output for the sums file element above can then be obtained as follows:

# Generate libbar-1.2.3.tar.xz.sums file
% wkrel generate path/to/libbar-1.2.3.tar.xz

# Print what would be written to the .sums file
% wkrel generate path/to/libbar-1.2.3.tar.xz sums
libbar-1.2.3.tar.xz (532 KiB):
  sha256: 9fd7bdb45d959a8eb39cc0b83c942759ec08856fe048767b97982d2723518535
Email Section

The email top level element configures how to gnerate release announcements to be sent by e-mail. The mapping may contain the following elements:

Element Contents
sender Name and e-mail address of the sender.
template Template text used for the e-mail body.
subject Template used for the e-mail subject. (Optional.)
recipients List of names and e-mail addresses of the recipients. (Optional.)

If the optional subject is not specified, the default value "%{package} %{version} released!" will be used. The following is a valid email configuration element, note how the variables element is used to provide a value for the %{url} expansion:

variables:
  url: "https://libfoo.org"

email:
  sender: "Foo Library release bot <noreply@foolib.org>"
  recipients:
    - "Foo Announcements <foo-announce@fooproject.org>"
    - "Distributor's Lists <foo-distributors@fooproject.org>"
  subject: "[Release] %{package} %{version} now available"
  template: |
    Hello,

    Today %{package} version %{version} has been released.
    You can find the full announcement at:

      %{url}/releases/%{version}.html

    The release team,
    %{date}

Note that if no recipients are specified, you will not be able to automatically send e-mails—generating them will be still possible, but you will need to edit and send them by hand, though.

Files Section

The files top level element is a mapping of strings to templates. For each element, it is possible to generate a companion file to a release package, with its contents being the result from expanding the associated template.

files:
  sums: "sha256 %{tar.sha256sum} %{tar.filename}"
  news: |
    # Changes in the %{version} release

    %{release-notes}

The wkrel generate subcommand can be used to generate the results from processing the configured templates.

Templates

Certain configuration values are taken as templates, which may reference variables. Variables are references by enclosing their name inside a pair of brackets prefixed by a percent sign: %{…}. Variables may contain any alphanumeric character, dashes (-), and underscores (_). The dot (.) character can be used to access subelements of variables which behave like mappings. The following are valid examples:

  • %{date} expands to a generated value corresponding to the current date.
  • %{package} expands to the value of the package configuration value.
  • %{email.sender} expands to the sender configuration item of the email configuration value (which is a mapping).

All configuration values are made available as variables, which means that both %{name} and %{variables.name} will expand to the same value.

The result of variable expansion can itself be a template, but its expansion needs to be triggered explicitly by using an asterisk as prefix of the variable name: %{*…}. The main usage of nested template expansion is reusing variables as template fragments, as in the following example:

variables:
  tar-checksums: |
    md5 %{tar.md5sum} %{tar.filename}
    sha1 %{tar.sha1sum} %{tar.filename}
    sha256 %{tar.sha256sum} %{tar.filename}

files:
  sums: |
    Checksums for %{package} %{version}:
    %{*tar-checksums}
Variables

The following variables are available for expansion in templates:

  • Named values configured in the top level variables element.
  • Cofiguration [top level elements](#Package Definition).
  • Extra generated content from the table below.
Variable Contents
%{date} The current date e.g. April 2nd, 2019.
%{packageid} Same as %{package}, in lowercase with whitespace characters removed.
%{release-notes} Release notes extracted from the file specified by the changelog configuration item.
%{release-tagline} String indicating the maturity of the release, e.g. This is a stable release in the 1.4 series..
%{stability} Expands to stable if the minor version number is even, otherwise to unstable.
%{version} Package version string i.e. the part matched by % from the pattern.
%{tar.*} Information about the package tarball file.

The package tarball object (%{tar.*}) provides the following variables:

Variable Contents
%{tar.filename} File name, without the leading path components.
%{tar.humansize} File size, with one decimal and magnitude suffix e.g. 1.3 MiB.
%{tar.size} File size, in bytes.
%{tar.md5sum} MD5 checksum of the file data.
%{tar.sha1sum} SHA1 checksum of the file data.
%{tar.sha256sum} SHA255 checksum of the file data.