Changes between Initial Version and Version 1 of WPE/Releasing

Timestamp:

Nov 8, 2019, 2:23:24 AM (6 years ago)

Author:

alex

Comment:

--

WPE/Releasing

@@ +1 @@
+= 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 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:
+
+{{{
+#!sh
+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 [wiki:"WebKitGTK/Releasing" 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 [https://trac.webkit.org/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\)' <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:
+
+{{{
+#!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
+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.
+
+{{{
+#!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.
+}}}
+
+== 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 <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 [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
+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:
+
+{{{
+#!sh
+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
+[https://github.com/Igalia/wpewebkit.org 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
+[https://github.com/WebPlatformForEmbedded/libwpe libwpe],
+[https://github.com/Igalia/WPEBackend-fdo WPEBackend-fdo], and
+[https://github.com/Igalia/cog 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:
+
+{{{
+#!sh
+git tag --sign -m'Version X.Y.Z' X.Y.Z [commitish]
+}}}
+