= Making a release of WPE = This wikipage is a complement of the page: [wiki:"WebKitGTK/Releasing" 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 the [wiki:"UsingGitWithWebKit" Using Git with WebKit] page. 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: {{{ #!sh git svn fetch git branch webkit-2.26 origin/webkitgtk-releases/webkit-2.26 git checkout webkit-2.26 }}} Be careful because '''the first time you download the Subversion branches this can take a lot of time'''. It is advisable to run this a few hours before working on a release. Incremental fetches will be much faster afterwards. Note that we always use the branch names with `X.Y` version numbers such as `webkit-2.26` to generate the releases; and not the `X.Y.Z` ones such as `webkit-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 [wiki:"WebKitGTK/Releasing" Making a release of WebKit/GTK] page. The next sections explain how to create 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 [wiki:"WebKitGTK/Releasing" 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: {{{ #!sh git log --grep='\(WPE\|GTK\|GStreamer\|SOUP\|GLib\)' ...  }}} 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—but be careful to remove from the WPE release notes those entries which only apply to the GTK port if you do this! 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: {{{ #!sh 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 import into the stable branch. Wiki pages like [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 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 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. A suitable version of `libwpe` needs to be installed (as it is a build dependency); it could be installed in its own directory (a prefix-installation), inside the JHBuild environment (which can be WebKit's internal one), or installed in the system directories. To configure with developer mode enabled and generate tarballs, use: {{{ #!sh 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. }}} Note that '''after changing version numbers tarballs must be re-created'''! == 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): {{{ #!sh 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 [https://jekyllrb.com/ 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 [https://github.com/WebKitGTK/webkitgtk.org/ 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: {{{ #!sh cd path/to/webkitgtk.org-git-clone/ ./webkit-release --from 'Rel Easer ' \     --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 [https://git.sr.ht/~aperezdc/webkit-releng-toolbelt wkrel tool], which supports all the WPE components (and WebKitGTK as well) but currently has a few less features. Example usage: {{{ #!sh # (Optional). Create a configuration file. Values override those in conf/*.yml mkdir ~/.config/wkrel cat > ~/.config/wkrel/user.yml <" 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: {{{ #!sh sftp -P 7575 www-data@wpewebkit.org:/var/www/wpewebkit/releases/ <