| 1 | = Making a release of WPE = |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | == Configuring Git to Fetch Stable Branches == |
| 6 | |
| 7 | Configure your WebKit checkout as instructed in https://trac.webkit.org/wiki/UsingGitWithWebKit |
| 8 | In particular, make sure to follow the instructions from the following sections: |
| 9 | |
| 10 | * Commit manually through git-svn directly |
| 11 | * Checking out Subversion branches |
| 12 | |
| 13 | To check out a stable branch, create a local Git branch which tracks the remote |
| 14 | one you are interested in, and then check it out. For example, for the `webkit-2.26` |
| 15 | stable release branch: |
| 16 | |
| 17 | {{{ |
| 18 | #!sh |
| 19 | git svn fetch |
| 20 | git branch webkit-2.26 origin/webkitgtk-releases/webkit-2.26 |
| 21 | git checkout webkit-2.26 |
| 22 | }}} |
| 23 | |
| 24 | 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. |
| 25 | |
| 26 | 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”). |
| 27 | |
| 28 | == Creating a release branch == |
| 29 | |
| 30 | In the '''new branch''': |
| 31 | |
| 32 | - The *libtool* version is imported from the `master` branch, and updated accordingly. |
| 33 | - The next package version will be `x.y.9z` (for the release candidates), and the first |
| 34 | stable release will be `x.y+1.0`. |
| 35 | |
| 36 | In the '''master branch''': |
| 37 | |
| 38 | * The '''libtool version''' is set to `(C+1, 0, A+1)` *after* the first stable release |
| 39 | (`x.y+1.0`) has been made from the stable branch. Note that `A` and `R` are the |
| 40 | values from the stable branch at the time of the `x.y+1.0` release: this bumps |
| 41 | if “new” API had been added. |
| 42 | * The package version is immediately set to `x.y+2.0`. |
| 43 | * In the first unstable release (x.y.1) we update the package version but not the libtool version, since |
| 44 | we don't really released the x.y.0 version. |
| 45 | |
| 46 | You can check more information about this in the [wiki:"WebKitGTK/Releasing" Making a release of WebKit/GTK] |
| 47 | |
| 48 | Next sections are creating the commit for the release. |
| 49 | |
| 50 | == Updating Version Numbers == |
| 51 | |
| 52 | Edit `Source/cmake/Options{WPE,GTK}.cmake`, change the '''package''' version |
| 53 | number in the `SET_PROJECT_VERSION()` macro and update the '''libtool soversion''' |
| 54 | in the `CALCULATE_LIBRARY_VERSIONS_FROM_LIBTOOL_TRIPLE()` one. |
| 55 | |
| 56 | Note: There is some discussion of libtool soversions and some more instructions |
| 57 | for doing releases [https://trac.webkit.org/wiki/WebKitGTK/Releasing here], |
| 58 | which should probably be merged with this page! |
| 59 | |
| 60 | == Write Release Notes == |
| 61 | |
| 62 | Release notes for user-visible changes are in “Source/WebKit/{gtk,wpe}/NEWS” |
| 63 | Check the commit logs since the last version and write down the release notes. |
| 64 | An useful command to only have to read commits relevant to the GLib ports is: |
| 65 | |
| 66 | {{{ |
| 67 | #!sh |
| 68 | git log --grep='\(WPE\|GTK\|GStreamer\|SOUP\|GLib\)' <oldrevision>... |
| 69 | }}} |
| 70 | |
| 71 | We are going to try to automate this task with and script and upstream it in the future, also sharing it with WebKitGTK. |
| 72 | |
| 73 | You can also check the changes from GTK's last release changes to use them, a lot of them are for both ports. |
| 74 | |
| 75 | Create a local commit with Git containing the edits to the `.cmake` and `NEWS` |
| 76 | files, then add a WebKit ChangeLog entry indicating that those changes are |
| 77 | unreviewed for a release: |
| 78 | |
| 79 | {{{ |
| 80 | #!sh |
| 81 | git add Source/cmake/OptionsWPE.cmake Source/WebKit/wpe/NEWS |
| 82 | git commit -m'Commit to prepare changelogs' |
| 83 | Scripts/Tools/prepare-ChangeLog -g @ |
| 84 | $EDITOR ChangeLog Source/WebKit/ChangeLog |
| 85 | git add ChangeLog Source/WebKit/ChangeLog |
| 86 | git commit --amend |
| 87 | }}} |
| 88 | |
| 89 | == Merging Patches to the Stable Branch == |
| 90 | |
| 91 | This is required only for releases done from a stable branch. Note that releases |
| 92 | with version ≥X.Y.90 are done from the stable branch as well. |
| 93 | |
| 94 | Before cutting a new release, we need to check whether there are pending merges to |
| 95 | impoty into the stable branch. Wiki pages like https://trac.webkit.org/wiki/WebKitGTK/2.26.x |
| 96 | list patches suggested by developers. |
| 97 | |
| 98 | First, check out and switch to the stable release branch (see above for configuration). |
| 99 | Then, for each patch listed for merging: |
| 100 | |
| 101 | 1. Find the Git commit-id from the Subversion revision, or from any other means (e.g. |
| 102 | the Git commit log). The command `git svn find-rev <svn-revision> master` can be |
| 103 | used to find the Git commit-id for commits present in `trunk`. |
| 104 | |
| 105 | 2. Cherry-pick the commit, resolving conflicts if needed. As a shortcut, a command |
| 106 | like `git cherry-pick $(git svn find-rev <svn-revision> master` can be used. |
| 107 | |
| 108 | 3. Use `git commit --amend`, prepend the string `Merge rNNN -` to |
| 109 | the first line, and remove the git-svn information from the last line of the |
| 110 | commit log. |
| 111 | |
| 112 | == Making Release Tarballs == |
| 113 | |
| 114 | In order to make release tarballs, you need the build directory configured with |
| 115 | the `DEVELOPER_MODE` option enabled: |
| 116 | |
| 117 | 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. |
| 118 | |
| 119 | {{{ |
| 120 | #!sh |
| 121 | cd path/to/WebKit |
| 122 | mkdir release-builddir && cd $_ |
| 123 | cmake -DPORT=WPE -DDEVELOPER_MODE=ON -GNinja .. |
| 124 | ninja dist # Create tarball |
| 125 | ninja distcheck # Also try building the contents of the tarball. |
| 126 | }}} |
| 127 | |
| 128 | == Version Numbers & Tagging == |
| 129 | |
| 130 | Once pending merges have been done (if any), edit `Options{WPE,GTK}.cmake` to update |
| 131 | the version numbers, add the release notes into `Source/WebKit/{wpe,gtk}/NEWS`, and |
| 132 | make a new local commit using Git. Then push the changes to the branch with |
| 133 | `git svn dcommit`. |
| 134 | |
| 135 | Finally, use `svn cp` to create the release “tag” into the Subversion repository |
| 136 | (a tag in Subversion is a branch which only has one revision with the state of |
| 137 | the tree at the time of making the release): |
| 138 | |
| 139 | {{{ |
| 140 | #!sh |
| 141 | svn cp \ |
| 142 | http://svn.webkit.org/repository/webkit/releases/WebKitGTK/webkit-2.26 \ |
| 143 | http://svn.webkit.org/repository/webkit/releases/WPE\ WebKit/webkit-2.26.0 |
| 144 | }}} |
| 145 | |
| 146 | |
| 147 | == Release Notes & Announcing == |
| 148 | |
| 149 | Release announcements are also uploaded to the project web sites, both of which |
| 150 | use [https://jekyllrb.com/ Jekyll] to generate the content from Markdown sources. |
| 151 | Make sure you have it installed to test your changes locally before pushing the |
| 152 | changes to the web sites. |
| 153 | |
| 154 | === WebKitGTK === |
| 155 | |
| 156 | For the GTK port we have a [https://github.com/WebKitGTK/webkitgtk.org/blob/master/webkit-release |
| 157 | release script] in the |
| 158 | [https://github.com/WebKitGTK/webkitgtk.org/ repository for the webkitgtk.org web site] |
| 159 | which can extract the release notes from a tarball, generate the auxiliary files |
| 160 | (`.sums`, `.news`, and the GPG `.asc` signature), and upload the results. It will also |
| 161 | generate a commit to update the web site. |
| 162 | |
| 163 | The `webkit-release` script is typically used from the top-level directory of the |
| 164 | web site repository: |
| 165 | |
| 166 | {{{ |
| 167 | #!sh |
| 168 | cd path/to/webkitgtk.org-git-clone/ |
| 169 | ./webkit-release --from 'Rel Easer <releaser@domain.tld>' \ |
| 170 | --host www-data@webkitgtk.org \ |
| 171 | --releases-dir /var/www/webkitgtkdotorg/releases \ |
| 172 | path/to/webkitgtk-X.Y.Z.tar.xz |
| 173 | }}} |
| 174 | |
| 175 | Note that the above will use the default PGP key configured for GnuPG to sign |
| 176 | the release tarball. Currently there is no option to configure which key to use. |
| 177 | |
| 178 | Now you can use `jekyll server --open-url --livereload` to assemble the web |
| 179 | site and have it opened locally in the browser, and it will be automatically |
| 180 | updated as files are edited. Once you are satisfied with the results, use |
| 181 | Git to push the changes to the repository. Once pushed, a periodic job will |
| 182 | pick the changes, rebuild the web site, and deploy the updates to the server. |
| 183 | |
| 184 | One last thing: update channel topic for the `#webkitgtk` Freenode IRC channel. |
| 185 | If you do cannot do it yourself, please let an operator know and they will do it |
| 186 | for you. |
| 187 | |
| 188 | |
| 189 | === WPE WebKit === |
| 190 | |
| 191 | The `webkit-release` script does *not* support tarballs of WPE tarballs. Instead, |
| 192 | you should use the [https://git.sr.ht/~aperezdc/webkit-releng-toolbelt wkrel tool], |
| 193 | which supports all the WPE components (and WebKitGTK as well) but currently has a |
| 194 | few less features. Example usage: |
| 195 | |
| 196 | {{{ |
| 197 | #!sh |
| 198 | # (Optional). Create a configuration file. Values override those in conf/*.yml |
| 199 | mkdir ~/.config/wkrel |
| 200 | cat > ~/.config/wkrel/user.yml <<EOF |
| 201 | gpgkey: 0x1234567890ABCDEF |
| 202 | email: |
| 203 | sender: "Rel Easer <releaser@domain.tld>" |
| 204 | EOF |
| 205 | # Generate the auxiliary release files, sign the tarball. |
| 206 | wkrel generate path/to/package-X.Y.Z.tar.xz |
| 207 | wkrel sign path/to/package-X.Y.Z.tar.xz |
| 208 | }}} |
| 209 | |
| 210 | The commands above will produce the following files in the same directory as |
| 211 | the tarball: |
| 212 | |
| 213 | * `package-X.Y.Z.tar.xz.asc`: PGP signature. |
| 214 | * `package-X.Y.Z.tar.xz.news`: File containing the changes for the version, |
| 215 | extracted from the NEWS file contained in the tarball. |
| 216 | * `package-X.Y.Z.tar.xz.sums`: Checksums for the tarball. |
| 217 | * `package-X.Y.Z.tar.xz.eml`: Release announcement e-mail. |
| 218 | * `package-X.Y.Z.tar.xz.md`: Release announcement in Markdown format, ready to |
| 219 | be used in the `wpewebkit.org` web site. |
| 220 | |
| 221 | In particular, you may want to double check the `.md` and `.eml` files |
| 222 | before proceeding. Now, use `sftp` to upload the tarballs and auxiliary |
| 223 | files: |
| 224 | |
| 225 | {{{ |
| 226 | #!sh |
| 227 | sftp www-data@wpewebkit.org:/var/www/wpewebkit/releases/ <<EOF |
| 228 | $(for i in package-X.Y.Z.tar.xz{,.asc,.sums,.news} ; do echo "put -a $i" ; done) |
| 229 | rm package-stable.tar.xz |
| 230 | symlink package-X.Y.Z.tar.xz package-stable.tar.xz |
| 231 | bye |
| 232 | EOF |
| 233 | }}} |
| 234 | |
| 235 | Copy the `.md` file to a local clone of the |
| 236 | [https://github.com/Igalia/wpewebkit.org wpewebkit.org web site repository] as a |
| 237 | new post, and use `jekyll server --livereload --open-url` to check the changes. |
| 238 | Once you are satisfied with the changes, use Git to commit the changes and push |
| 239 | them to the repository; a periodic job will pick the changes, rebuild the web site, |
| 240 | and deploy the updates to the server. |
| 241 | |
| 242 | Lastly, remember that the `wkrel` script does not (yet) send itself the announcement |
| 243 | e-mails, so after reviewing the generated `.eml` file schedule it for delivery, for |
| 244 | example with `sendmail -t < package-X.Y.Z.tar.xz.eml`. |
| 245 | |
| 246 | |
| 247 | === WPE Components in GitHub === |
| 248 | |
| 249 | For the WPE components which have their repositories hosted in GitHub (currently |
| 250 | [https://github.com/WebPlatformForEmbedded/libwpe libwpe], |
| 251 | [https://github.com/Igalia/WPEBackend-fdo WPEBackend-fdo], and |
| 252 | [https://github.com/Igalia/cog Cog]) the procedure is the same as for WPE WebKit |
| 253 | releases (see previous section): the `wkrel` script supports generating content |
| 254 | from their tarballs, and should be announced in the same way (post in the website |
| 255 | and e-mail). |
| 256 | |
| 257 | Additionally, a Git release tag must be pushed to the corresponding Git repository, |
| 258 | preferably signed with the same PGP key used to sign the release tarball. The signed |
| 259 | tag can be created with: |
| 260 | |
| 261 | {{{ |
| 262 | #!sh |
| 263 | git tag --sign -m'Version X.Y.Z' X.Y.Z [commitish] |
| 264 | }}} |
| 265 | |