Making a release of WPE

This wikipage is a complement of the page: Making a release of WebKit/GTK. At some point we plan to merge them and create just one to simplify all the information.

Configuring Git to Fetch Stable Branches

Configure your WebKit checkout as instructed in ​https://trac.webkit.org/wiki/UsingGitWithWebKit In particular, make sure to follow the instructions from the following sections:

• Commit manually through git-svn directly
• Checking out Subversion branches

To check out a stable branch, create a local Git branch which tracks the remote one you are interested in, and then check it out. For example, for the webkit-2.26 stable release branch:

git svn fetch
git branch webkit-2.26 origin/webkitgtk-releases/webkit-2.26
git checkout webkit-2.26

Be careful with this the first time you download the svn branches because it can take a lot of time, prepare the whole thing hour before you want to do the release.

We always use the branches with x.y numbers such as 2.26 to generate the releases, Not the x.y.z ones, such as 2.26.2 (which correspond to the Subversion release “tags”).

Creating a release branch

In the new branch:

• The *libtool* version is imported from the master branch, and updated accordingly.
• The next package version will be x.y.9z (for the release candidates), and the first stable release will be x.y+1.0.

In the master branch:

• The libtool version is set to (C+1, 0, A+1) *after* the first stable release (x.y+1.0) has been made from the stable branch. Note that A and R are the values from the stable branch at the time of the x.y+1.0 release: this bumps if “new” API had been added.
• The package version is immediately set to x.y+2.0.
• In the first unstable release (x.y.1) we update the package version but not the libtool version, since we don't really released the x.y.0 version.

You can check more information about this in the Making a release of WebKit/GTK

Next sections are creating the commit for the release.

Updating Version Numbers

Edit Source/cmake/Options{WPE,GTK}.cmake, change the package version number in the SET_PROJECT_VERSION() macro and update the libtool soversion in the CALCULATE_LIBRARY_VERSIONS_FROM_LIBTOOL_TRIPLE() one.

Note: There is some discussion of libtool soversions and some more instructions

for doing releases ​here,

which should probably be merged with this page!

Write Release Notes

Release notes for user-visible changes are in “Source/WebKit/{gtk,wpe}/NEWS” Check the commit logs since the last version and write down the release notes. An useful command to only have to read commits relevant to the GLib ports is:

git log --grep='\(WPE\|GTK\|GStreamer\|SOUP\|GLib\)' <oldrevision>... 

We are going to try to automate this task with and script and upstream it in the future, also sharing it with WebKitGTK.

You can also check the changes from GTK's last release changes to use them, a lot of them are for both ports.

Create a local commit with Git containing the edits to the .cmake and NEWS files, then add a WebKit ChangeLog entry indicating that those changes are unreviewed for a release:

git add Source/cmake/OptionsWPE.cmake Source/WebKit/wpe/NEWS
git commit -m'Commit to prepare changelogs'
Scripts/Tools/prepare-ChangeLog -g @
$EDITOR ChangeLog Source/WebKit/ChangeLog
git add ChangeLog Source/WebKit/ChangeLog
git commit --amend

Merging Patches to the Stable Branch

This is required only for releases done from a stable branch. Note that releases with version ≥X.Y.90 are done from the stable branch as well.

Before cutting a new release, we need to check whether there are pending merges to impoty into the stable branch. Wiki pages like ​https://trac.webkit.org/wiki/WebKitGTK/2.26.x list patches suggested by developers.

First, check out and switch to the stable release branch (see above for configuration). Then, for each patch listed for merging:

1. Find the Git commit-id from the Subversion revision, or from any other means (e.g. the Git commit log). The command git svn find-rev <svn-revision> master can be used to find the Git commit-id for commits present in trunk.

2. Cherry-pick the commit, resolving conflicts if needed. As a shortcut, a command like git cherry-pick $(git svn find-rev <svn-revision> master can be used.

3. Use git commit --amend, prepend the string Merge rNNN - to the first line, and remove the git-svn information from the last line of the commit log.

Making Release Tarballs

In order to make release tarballs, you need the build directory configured with the DEVELOPER_MODE option enabled:

In order to do this we need a version of libwpe in the paths, we can compile them in a directory, inside jhbuild or install them in the system.

cd path/to/WebKit
mkdir release-builddir && cd $_
cmake -DPORT=WPE -DDEVELOPER_MODE=ON -GNinja ..
ninja dist       # Create tarball
ninja distcheck  # Also try building the contents of the tarball.

Version Numbers & Tagging

Once pending merges have been done (if any), edit Options{WPE,GTK}.cmake to update the version numbers, add the release notes into Source/WebKit/{wpe,gtk}/NEWS, and make a new local commit using Git. Then push the changes to the branch with git svn dcommit.

Finally, use svn cp to create the release “tag” into the Subversion repository (a tag in Subversion is a branch which only has one revision with the state of the tree at the time of making the release):

svn cp \
  http://svn.webkit.org/repository/webkit/releases/WebKitGTK/webkit-2.26 \
  http://svn.webkit.org/repository/webkit/releases/WPE\ WebKit/webkit-2.26.0

Release Notes & Announcing

Release announcements are also uploaded to the project web sites, both of which use ​Jekyll to generate the content from Markdown sources. Make sure you have it installed to test your changes locally before pushing the changes to the web sites.

WebKitGTK

For the GTK port we have a [​https://github.com/WebKitGTK/webkitgtk.org/blob/master/webkit-release release script] in the ​repository for the webkitgtk.org web site which can extract the release notes from a tarball, generate the auxiliary files (.sums, .news, and the GPG .asc signature), and upload the results. It will also generate a commit to update the web site.

The webkit-release script is typically used from the top-level directory of the web site repository:

cd path/to/webkitgtk.org-git-clone/
./webkit-release --from 'Rel Easer <releaser@domain.tld>' \
    --host www-data@webkitgtk.org \
    --releases-dir /var/www/webkitgtkdotorg/releases \
    path/to/webkitgtk-X.Y.Z.tar.xz

Note that the above will use the default PGP key configured for GnuPG to sign the release tarball. Currently there is no option to configure which key to use.

Now you can use jekyll server --open-url --livereload to assemble the web site and have it opened locally in the browser, and it will be automatically updated as files are edited. Once you are satisfied with the results, use Git to push the changes to the repository. Once pushed, a periodic job will pick the changes, rebuild the web site, and deploy the updates to the server.

One last thing: update channel topic for the #webkitgtk Freenode IRC channel. If you do cannot do it yourself, please let an operator know and they will do it for you.

WPE WebKit

The webkit-release script does *not* support tarballs of WPE tarballs. Instead, you should use the ​wkrel tool, which supports all the WPE components (and WebKitGTK as well) but currently has a few less features. Example usage:

# (Optional). Create a configuration file. Values override those in conf/*.yml
mkdir ~/.config/wkrel
cat > ~/.config/wkrel/user.yml <<EOF
gpgkey: 0x1234567890ABCDEF
email:
  sender: "Rel Easer <releaser@domain.tld>"
EOF
# Generate the auxiliary release files, sign the tarball.
wkrel generate path/to/package-X.Y.Z.tar.xz
wkrel sign path/to/package-X.Y.Z.tar.xz

The commands above will produce the following files in the same directory as the tarball:

• package-X.Y.Z.tar.xz.asc: PGP signature.
• package-X.Y.Z.tar.xz.news: File containing the changes for the version,

extracted from the NEWS file contained in the tarball.

• package-X.Y.Z.tar.xz.sums: Checksums for the tarball.
• package-X.Y.Z.tar.xz.eml: Release announcement e-mail.
• package-X.Y.Z.tar.xz.md: Release announcement in Markdown format, ready to be used in the wpewebkit.org web site.

In particular, you may want to double check the .md and .eml files before proceeding. Now, use sftp to upload the tarballs and auxiliary files:

sftp www-data@wpewebkit.org:/var/www/wpewebkit/releases/ <<EOF
$(for i in package-X.Y.Z.tar.xz{,.asc,.sums,.news} ; do echo "put -a $i" ; done)
rm package-stable.tar.xz
symlink package-X.Y.Z.tar.xz package-stable.tar.xz
bye
EOF

Copy the .md file to a local clone of the ​wpewebkit.org web site repository as a new post, and use jekyll server --livereload --open-url to check the changes. Once you are satisfied with the changes, use Git to commit the changes and push them to the repository; a periodic job will pick the changes, rebuild the web site, and deploy the updates to the server.

Lastly, remember that the wkrel script does not (yet) send itself the announcement e-mails, so after reviewing the generated .eml file schedule it for delivery, for example with sendmail -t < package-X.Y.Z.tar.xz.eml.

WPE Components in GitHub

For the WPE components which have their repositories hosted in GitHub (currently ​libwpe, ​WPEBackend-fdo, and ​Cog) the procedure is the same as for WPE WebKit releases (see previous section): the wkrel script supports generating content from their tarballs, and should be announced in the same way (post in the website and e-mail).

Additionally, a Git release tag must be pushed to the corresponding Git repository, preferably signed with the same PGP key used to sign the release tarball. The signed tag can be created with:

git tag --sign -m'Version X.Y.Z' X.Y.Z [commitish]