#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:

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 generate release announcements to be sent by e-mail. The mapping may contain the following elements:

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.

#Extract-Tarballs Section

The extract-tarballs top level element is a mapping of templates to templates. Each element indicates the path from the release tarball from which files will be picked, with the value the destination tarball name.

extract-tarballs:
  "%{packageid}-%{version}/Documentation": "%{packageid}-html-%{version}.tar.xz"

The example above will pick the Documentation/ directory (and all its regular file contents) from the release tarball and generate a new tarball containing only that directory.

#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.

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