Repository: incubator-guacamole-website Updated Branches: refs/heads/master 434a74eec -> 87ca4ae56
Document Apache Guacamole release procedures. Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/commit/20dc7f6b Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/tree/20dc7f6b Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/diff/20dc7f6b Branch: refs/heads/master Commit: 20dc7f6b4d70b31404a5a081d3a3a884625ef676 Parents: 434a74e Author: Michael Jumper <[email protected]> Authored: Sun Jan 8 13:23:52 2017 -0800 Committer: Michael Jumper <[email protected]> Committed: Mon Mar 13 14:14:22 2017 -0700 ---------------------------------------------------------------------- open-source.md | 7 + release-procedure-part1.md | 121 ++++++++++++++ release-procedure-part2.md | 350 ++++++++++++++++++++++++++++++++++++++++ release-procedure-part3.md | 109 +++++++++++++ release-procedure-part4.md | 97 +++++++++++ 5 files changed, 684 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/20dc7f6b/open-source.md ---------------------------------------------------------------------- diff --git a/open-source.md b/open-source.md index 004529c..3fe811e 100644 --- a/open-source.md +++ b/open-source.md @@ -100,6 +100,13 @@ a committer not otherwise directly involved in those changes. * [Managing pull requests](/pull-requests/) * [Style guidelines](/guac-style/) +### Release procedures: + +* [Beginning the release process](/release-procedures-part1/) +* [Producing a release candidate](/release-procedures-part2/) +* [Promoting a release candidate to release](/release-procedures-part3/) +* [Announcing the release](/release-procedures-part4/) + PPMC members ------------ http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/20dc7f6b/release-procedure-part1.md ---------------------------------------------------------------------- diff --git a/release-procedure-part1.md b/release-procedure-part1.md new file mode 100644 index 0000000..fee1851 --- /dev/null +++ b/release-procedure-part1.md @@ -0,0 +1,121 @@ +--- +layout: page +title: Beginning the release process +permalink: /release-procedures-part1/ +--- + +* Table of contents +{:toc} + +Create a discussion thread for the release {#discuss-thread} +------------------------------------------------------------ + +Beginning a new release candidate should not be a unilateral decision. There is +no requirement that an official vote be held prior to starting a release +candidate, but there needs to be some discussion via a `[DISCUSS]` thread on +<[email protected]> to gauge whether the time is right for a +release. + +Development of Apache Guacamole is not halted when a release is being prepared, +but the main development tree is forked. With this in mind, it is best to only +begin the release process when: + + * The development community agrees (or, more likely, doesn't disagree) that + the scope of the release can be finalized (no new features/fixes/etc. will + be considered for the release). + * The non-release development line is unlikely to diverge so far from the + release development line that it is detrimental to the project. + +All issues which should be part of the release must be tagged as such within +JIRA (their "Fix Version" field should point to the release). + +Example: [the [DISCUSS] thread for 0.9.11-incubating](http://mail-archives.apache.org/mod_mbox/incubator-guacamole-dev/201701.mbox/%3CCALKeL-OO7MMpvtZkFXbkrkRKVokKHgdANTpMVceaH41MnUu7Eg%40mail.gmail.com%3E) + +Create the release branch {#release-branch} +------------------------------------------- + +When a release has been decided, release-specific branches need to be created +to isolate the development line of the release from that of the main `master` +branch. This allows development on `master` to continue, while allowing the +contents of the release to remain within the agreed scope. + +Create a new `staging/[VERSION]` branch for each of the following repositories, +where `[VERSION]` is the version of the upcoming release, such as +"0.9.11-incubating": + + * [`incubator-guacamole-client`](https://github.com/apache/incubator-guacamole-client) + * [`incubator-guacamole-server`](https://github.com/apache/incubator-guacamole-server) + * [`incubator-guacamole-manual`](https://github.com/apache/incubator-guacamole-manual) + +Note that *the +[`incubator-guacamole-website`](https://github.com/apache/incubator-guacamole-website) +repository does not get a release branch*. The website points to release +artifacts, etc. but is not itself part of the release. + +Once the release branch is made, all release-specific changes must be made +against the release branch *only*. Pull requests for changes related to the +release must be merged directly to the release branch, with the release branch +continually merged back to `master` with each such change. + + +Bump version numbers {#bump-version} +------------------------------------ + +The version numbers of Apache Guacamole's various components do not get bumped +until a release is being prepared. With the exception of any in-scope changes +which are in-progress (which should usually be minimal), bumping the version +numbers is one of the final development steps before the first release +candidate. + +Only the version numbers of modified components should be bumped. That said, +bumping the version numbers of some components will result in their +dependencies being modified, and thus bumped as well. For example: + + * If `guacamole-ext` is modified, all extensions and `guacamole` itself will + need to depend on the new version of `guacamole-ext`. + * If `guacamole` is modified (this has been the case for all past releases), + all extensions will need to be modified to specify the correct version + number in their `guac-manifest.json`. + +### Bumping the version of `incubator-guacamole-server` + +The main locations which need modification within `incubator-guacamole-server` +are: + + * `configure.ac` + * `doc/Doxyfile` (if libguac has been modified) + * libtool version-info within `src/libguac/Makefile.am` (if libguac has been + modified) + * `bin/guacctl` + * The manpages for `guacd`, `guacenc`, and `guacd.conf`. + +Example: [the pull request for bumping `incubator-guacamole-server` to 0.9.11-incubating](https://github.com/apache/incubator-guacamole-server/pull/34) + +### Bumping the version of `incubator-guacamole-client` + +The main locations which need modification within `incubator-guacamole-client` +are: + + * The `pom.xml` of any modified project, as well as any project which depends + on a modified project (and is thus modified itself). **Don't forget the + example project in `doc/guacamole-example`!** + * The `guac-manifest.json` of any extension. + * The `Guacamole.API_VERSION` value declared within `Version.js` (if + `guacamole-common-js` has been modified). + +Example: [the pull request for bumping `incubator-guacamole-client` to 0.9.11-incubating](https://github.com/apache/incubator-guacamole-client/pull/103) + +### Updating `incubator-guacamole-manual` accordingly + +The manual (`incubator-guacamole-manual`) will also need to be updated to point +to the latest versions of everything. In most cases, this involves simply +replacing the old version number with the new version number wherever it +occurs, but the process needs to be selective if not all components have been +modified. In particular, watch out for: + + * The need to document new database schema upgrade scripts. + * The need to update the webapp, authentication, and protocol plugin + tutorials. + +Example: [the pull request for bumping `incubator-guacamole-manual` to 0.9.11-incubating](https://github.com/apache/incubator-guacamole-manual/pull/23) + http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/20dc7f6b/release-procedure-part2.md ---------------------------------------------------------------------- diff --git a/release-procedure-part2.md b/release-procedure-part2.md new file mode 100644 index 0000000..07e0398 --- /dev/null +++ b/release-procedure-part2.md @@ -0,0 +1,350 @@ +--- +layout: page +title: Producing a release candidate +permalink: /release-procedures-part2/ +--- + +* Table of contents +{:toc} + +Tag the release candidate {#tag-rc} +----------------------------------- + +Once [the release process has begun](/release-procedures-part1/) and the +release has been **thoroughly tested**, the git repositories must be tagged for +a new release candidate. These tags are made off the release branch (*not* off +`master`), and are in the format `[VERSION]-RC[N]`, where `[VERSION]` is the +version of the upcoming release and `[N]` is the number of the release +candidate: + + $ git tag -m "Release 0.9.11-incubating - RC1." 0.9.11-incubating-RC1 + $ git push upstream 0.9.11-incubating-RC1 + +Each repository relevant to the release must be tagged. At this point, this +will be every repository that has a release branch. This *never* includes +`incubator-guacamole-website`, which is not part of the release. + +Example: [the +"0.9.10-incubating-RC3" tag on +incubator-guacamole-server](https://git1-us-west.apache.org/repos/asf?p=incubator-guacamole-server.git;a=tag;h=6c2bc47a93899cf00a869e7a2a5416fd5b081ed3) + + +Sign and upload release artifacts {#upload-rc} +---------------------------------------------- + +Create and sign release artifacts for all modified components, uploading to +Apache's dev dist via SVN (*NOT* the release dist), grouping the artifacts +within `binary/` and `source/` subdirectories of a top-level, RC-specific +subdirectory (named in the same `[VERSION]-RC[N]` format as the [repository +tag](#tag-rc)). + +Creating the source and binary artifacts involves building the components of +Guacamole normally. The process for producing signatures and uploading the +artifacts will depend on whether the artifacts are being deployed to a Maven +repository. + +**If your PGP key is not already present in the `KEYS` file, you will need to +add it prior to signing artifacts.** + +### Normal source / binary artifacts {#artifacts} + +There are currently two source artifacts: + + * `guacamole-client-[VERSION].tar.gz` + * `guacamole-server-[VERSION].tar.gz` + +`guacamole-client-[VERSION].tar.gz` is created automatically when +`incubator-guacamole-client` is built with `mvn clean install`. +`guacamole-server-[VERSION].tar.gz` can be built manually by running `make +dist` within `incubator-guacamole-server`. The `Makefile`, etc. will need to +have been generated first by running `autoreconf -fi` followed by +`./configure`. + +`incubator-guacamole-server` does not provide any convenience binaries, but +`incubator-guacamole-client` does: + + * `guacamole-[VERSION].war` + * `guacamole-auth-duo-[VERSION].tar.gz` + * `guacamole-auth-header-[VERSION].tar.gz` + * `guacamole-auth-jdbc-[VERSION].tar.gz` + * `guacamole-auth-ldap-[VERSION].tar.gz` + * `guacamole-auth-noauth-[VERSION].tar.gz` + +Each of the above can be found within the `incubator-guacamole-client` source +tree once it has been built with `mvn clean install`. + +Producing the required MD5 and SHA256 checksums for a given artifact is very +straightforward: + + $ md5sum FILENAME > FILENAME.md5 + $ sha256sum FILENAME > FILENAME.sha + +To produce the PGP signature for a given artifact, use `gpg`, as documented in +Apache's own [release signing documentation](https://www.apache.org/dev/release-signing.html#openpgp-ascii-detach-sig): + + $ gpg --armor --output FILENAME.asc --detach-sig FILENAME + +Example: [the SVN commit uploading RC1 of 0.9.10-incubating (r17053)](https://dist.apache.org/repos/dist/dev/incubator/guacamole/?p=17053) + +### Maven artifacts {#staging-maven} + +The following Maven subprojects of `incubator-guacamole-client` must be +uploaded to Apache's Nexus: + + * `guacamole-common` (`.jar`, source, and javadoc) + * `guacamole-common-js` (`.zip` only) + * `guacamole-ext` (`.jar`, source, and javadoc) + +Uploading to [Apache's Nexus repository](https://repository.apache.org/) +requires that your username and password be stored within your Maven +`~/.m2/settings.xml`: + + <settings> + <servers> + <server> + <id>apache</id> + <username>YOUR-USERNAME</username> + <password>YOUR-PASSWORD</password> + </server> + </servers> + </settings> + +The ID of the server is arbitrary but must match the `repositoryId` value given +to Maven. The examples here use `apache`. Most artifacts are Java `.jar` files +with corresponding JavaDoc and source jars. Each of these must be signed and +uploaded individually using the `gpg:sign-and-deploy-file` mojo: + + $ mvn gpg:sign-and-deploy-file \ + -Durl=https://repository.apache.org/service/local/staging/deploy/maven2 \ + -DrepositoryId=apache -DpomFile=guacamole-common/pom.xml \ + -Dfile=guacamole-common/target/guacamole-common-0.9.10-incubating.jar + + $ mvn gpg:sign-and-deploy-file \ + -Durl=https://repository.apache.org/service/local/staging/deploy/maven2 \ + -DrepositoryId=apache -DpomFile=guacamole-common/pom.xml \ + -Dfile=guacamole-common/target/guacamole-common-0.9.10-incubating-javadoc.jar \ + -Dclassifier=javadoc + + $ mvn gpg:sign-and-deploy-file \ + -Durl=https://repository.apache.org/service/local/staging/deploy/maven2 \ + -DrepositoryId=apache -DpomFile=guacamole-common/pom.xml \ + -Dfile=guacamole-common/target/guacamole-common-0.9.10-incubating-sources.jar \ + -Dclassifier=sources + +The above will need to be done for both `guacamole-common` and `guacamole-ext`, +assuming both have been modified for the release. For JavaScript artifacts like +`guacamole-common-js` which produce a single `.zip` file, only the `.zip` file +needs to be uploaded. The command for this is slightly different: + + $ mvn gpg:sign-and-deploy-file \ + -Durl=https://repository.apache.org/service/local/staging/deploy/maven2 \ + -DrepositoryId=apache \ + -DpomFile=guacamole-common-js/pom.xml \ + -Dfile=guacamole-common-js/target/guacamole-common-js-0.9.10-incubating.zip \ + -Dpackaging=zip + +Once everything has been uploaded, log into Apache's Nexus at +https://repository.apache.org/, locate the staging repository which was +automatically created, and verify things look as expected. Assuming everything +looks good, select close staging repository to make it publicly available; the +URL of the repository will need to be provided in the various VOTE emails. + +### Docker images + +Both guacamole-client and guacamole-server have associated Docker images which +are produced along with releases as a form of convenience binaries. These +images are `guacamole/guacamole` and `guacamole/guacd` respectively, both +hosted under the Apache Guacamole project's [Docker Hub +account](http://guacamole.incubator.apache.org/releases/). + +When building the Docker images, keep in mind: + +1. You should run `git clean -xfd .` first, to ensure the build context + uploaded to the Docker daemon is minimal, and that future builds of the + exact same source will not result in different images (this serves as a + pre-release sanity check). +2. You **MUST NOT** update the `latest` tag on Docker Hub, as this must only + point to the latest stable release. +3. When building a Docker image with the intent of pushing to a specific tag, + the Docker image must be built with that tag. + +For example, to build the `guacamole/guacamole` Docker image for the current +release candidate, from within the top-level `incubator-guacamole-client` +directory: + + $ git clean -xfd . + $ sudo docker build -t guacamole/guacamole:0.9.11-incubating-RC1 . + $ sudo docker push guacamole/guacamole:0.9.11-incubating-RC1 + + +Upload documentation and release notes {#upload-docs} +----------------------------------------------------- + +The draft release notes and updated documentation both need to be uploaded to +the website prior to [calling the PPMC vote](#ppmc-vote). These changes should +be handled like any other website changes - via pull requests against the +`incubator-guacamole-website` repository. **DO NOT UPDATE THE TOP-LEVEL +DOCUMENTATION SYMBOLIC LINKS!** The top-level symbolic links in the `doc/` +directory of `incubator-guacamole-website` point to the documentation for the +latest release, and are thus only updated once the release is complete. + +Take a look at past release notes to get an idea for the expected format. There +is no hard-set requirement for the format of release notes, but things should +be as consistent as possible. Use JIRA to query the issues which have been +completed for the release, manually excluding issues which relate only to +other issues already in the release (bug fixes for a release-specific change, +for example). + +Because the script that handles updating project websites often fails to update +for large commits (see [INFRA-10751](https://issues.apache.org/jira/browse/INFRA-10751)), uploading documentation first, waiting a bit, and *then* uploading +the release notes has a greater chance of working. Splitting the two uploads +also helps facilitate code review, as the release notes will be buried in a sea +of auto-generated HTML otherwise. + +Examples: + + * [The draft +release notes for 0.9.10-incubating-RC3](https://github.com/apache/incubator-guacamole-website/blob/67adf0802701d696f9dc1a90229da694f4cebbaa/_releases/0.9.10-incubating.md) + * [The updated documentation for 0.9.10-incubating](https://github.com/apache/incubator-guacamole-website/tree/master/doc/0.9.10-incubating) + +Create the PPMC `[VOTE]` thread {#ppmc-vote} +-------------------------------------------- + +Once the above has been completed, request a vote with an email to +<[email protected]> titled `[VOTE] Release Apache Guacamole +[VERSION] (RC[N])`, containing the following: + +``` +Hello all, + +The [NTH] release candidate for Apache Guacamole [VERSION] has been +uploaded and is ready for VOTE. The draft release notes (along with links +to artifacts, signatures/checksums, and updated documentation) can be found +here: + +http://guacamole.incubator.apache.org/releases/[VERSION]/ + +The git tag for all relevant repositories is "[VERSION]-RC[N]": + +https://github.com/apache/incubator-guacamole-client/tree/[VERSION]-RC[N] +https://github.com/apache/incubator-guacamole-server/tree/[VERSION]-RC[N] +https://github.com/apache/incubator-guacamole-manual/tree/[VERSION]-RC[N] + +Build instructions are included in the manual, which is part of the updated +documentation referenced above. For convenience: + +http://guacamole.incubator.apache.org/doc/[VERSION]/gug/installing-guacamole.html + +Maven artifacts for guacamole-common, guacamole-common-js, and +guacamole-ext can be found in the following staging repository: + +[STAGING REPOSITORY URL] + +Source and binary distributions (also linked within the release notes): + +https://dist.apache.org/repos/dist/dev/incubator/guacamole/[VERSION]-RC[N]/ + +Artifacts have been signed with the "[EMAIL]" key listed in: + +https://dist.apache.org/repos/dist/dev/incubator/guacamole/KEYS + +Please review and vote: + +[ ] +1 Approve the release +[ ] -1 Don't approve the release (please provide specific comments) + +This vote will be open for at least 72 hours. + +Here is my +1. + +Thanks, + +[YOU] +``` + +Where `[VERSION]` is the release version, `[N]` and `[NTH]` are the number of +the release candidate, `[STAGING REPOSITORY URL]` is the URL of [the staging +repository created earlier](#staging-maven), `[EMAIL]` is the email address +associated with the PGP key used to sign the release artifacts, and `[YOU]` is +your name. Obviously, alter the email as necessary if the scope of the release +is different. + +Please note that, though community input is welcome, *only PPMC votes count +toward the required three "+1" votes*. + +Example: [the 0.9.10-incubating-RC3 PPMC VOTE email](http://mail-archives.apache.org/mod_mbox/incubator-guacamole-dev/201612.mbox/%3CCALKeL-PKQxOYqZCvhH6_ZF33Zo_LUZjLVZzTh%2B0VRipgsNxQ1g%40mail.gmail.com%3E) + +If any release-blocking issues are discovered, the vote must be canceled and +development must resume, followed by another release candidate (prepared as +above) intended to address those issues. + + +Create the IPMC `[VOTE]` thread {#ipmc-vote} +-------------------------------------------- + +If/when the PPMC vote passes, another vote must be started for the IPMC. Only +IPMC votes are binding here. Send an email to <[email protected]> +titled `[VOTE] Release Apache Guacamole [VERSION] (RC[N])` containing the +following: + +``` +Hello Incubator PMC, + +The Apache Guacamole community has voted on and approved a proposal to +release Apache Guacamole [VERSION]. + +We now kindly request that the Incubator PMC members review and vote +on this incubator release. + +The VOTE RESULT is here: + +[LINK TO VOTE RESULT] + +The draft release notes (along with links to artifacts, +signatures/checksums, and updated documentation) can be found here: + +http://guacamole.incubator.apache.org/releases/[VERSION]/ + +The git tag for all relevant repositories is "[VERSION]-RC[N]": + +https://github.com/apache/incubator-guacamole-client/tree/[VERSION]-RC[N] +https://github.com/apache/incubator-guacamole-server/tree/[VERSION]-RC[N] +https://github.com/apache/incubator-guacamole-manual/tree/[VERSION]-RC[N] + +Build instructions are included in the manual, which is part of the +updated documentation referenced above. For convenience: + +http://guacamole.incubator.apache.org/doc/[VERSION]/gug/installing-guacamole.html + +Maven artifacts for guacamole-common, guacamole-common-js, and +guacamole-ext can be found in the following staging repository: + +[STAGING REPOSITORY URL] + +Source and binary distributions (also linked within the release notes): + +https://dist.apache.org/repos/dist/dev/incubator/guacamole/[VERSION-RC[N]/ + +Artifacts have been signed with the "[EMAIL]" key listed in: + +https://dist.apache.org/repos/dist/dev/incubator/guacamole/KEYS + +Please review and vote: + +[ ] +1 Approve the release +[ ] -1 Don't approve the release (please provide specific comments) + +This vote will be open for at least 72 hours. + +Thanks, + +[YOU] +``` + +Where `[LINK TO VOTE RESULT]` the permalink to the specific email calling the +result of [the PPMC vote](#ppmc-vote) on the [public archive of [email protected]](http://mail-archives.apache.org/mod_mbox/incubator-guacamole-dev/), +and all other fields are as described for [the PPMC vote email](#ppmc-vote). + +Example: [the 0.9.10-incubating-RC3 IPMC VOTE email](http://mail-archives.apache.org/mod_mbox/incubator-general/201612.mbox/%3CCALKeL-MQmTi1fW%2BGsvFvN21D-ECfHEpf7hwQN5rB-U1JmfAXtQ%40mail.gmail.com%3E) + http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/20dc7f6b/release-procedure-part3.md ---------------------------------------------------------------------- diff --git a/release-procedure-part3.md b/release-procedure-part3.md new file mode 100644 index 0000000..ecb140c --- /dev/null +++ b/release-procedure-part3.md @@ -0,0 +1,109 @@ +--- +layout: page +title: Promoting a release candidate to release +permalink: /release-procedures-part3/ +--- + +* Table of contents +{:toc} + +Delete the release branch {#delete-branch} +------------------------------------------ + +Once [the PPMC vote](/release-procedures-part2/#ppmc-vote) and [IPMC +vote](/release-procedures-part2/#ipmc-vote) for the release have passed, the +release branches [which were created +previously](/release-procedures-part1/#release-branch) must be deleted. +Assuming they were properly merged back to `master` as release-specific changes +were made, deleting these branches with `git branch -d` will succeed without +warnings. If git refuses to delete the branches because commits are missing +from `master`, **something is horribly wrong, and the release needs to be +rechecked**. + + $ git checkout master + $ git branch -d staging/0.9.11-incubating + $ git push upstream :staging/0.9.11-incubating + +Tag the final version of the release {#final-tag} +------------------------------------------------- + +The specific point in the git history that the release was made must be marked +with a new tag, pointing to the exact same commit as the last [tagged release +candidate](/release-procedures-part2/#tag-rc). This tag must be made in the +format `[VERSION]`, where `[VERSION]` is the version of the release: + + $ git tag -m "Release 0.9.11-incubating." 0.9.11-incubating + $ git push upstream 0.9.11-incubating + +Just as with release candidates, each repository relevant to the release must +be tagged. This will be every repository that had a release branch (the release +branch having been [deleted earlier](#delete-branch)) and *never* includes +`incubator-guacamole-website`, which is not part of the release. + +Example: [the "0.9.10-incubating" tag on +incubator-guacamole-server](https://git1-us-west.apache.org/repos/asf?p=incubator-guacamole-server.git;a=tag;h=0875ca8f4e86b942b466cfebf84cc33c47095130) + + +Upload final release artifacts {#final-upload} +---------------------------------------------- + +### Artifacts in dist SVN + +The release artifacts and their signatures come from the release candidate +which was approved via the various VOTEs. These artifacts are already present +in the SVN dist area under `dev/`, and need to be moved to the analogous area +under `release/`. *This must be done using `svn mv`*, with the directory +containing the artifacts and signatures being renamed from `[VERSION]-RC[N]` to +`[VERSION`] in the process. + + $ svn mv dev/incubator/guacamole/0.9.11-incubating-RC1 release/incubator/guacamole/0.9.11-incubating + $ svn commit -m "Promote Apache Guacamole 0.9.11-incubating-RC1 artifacts to 0.9.11-incubating release." + +Note that, once this has finished, **YOU MUST STILL WAIT AT LEAST 24 HOURS TO +ALLOW THE [MIRRORS](https://www.apache.org/mirrors/) TIME TO SYNC** before +announcing the release. + +### Maven artifacts + +For the Maven artifacts to become generally available at +<https://repository.apache.org/>, and for those artifacts to be synced with +[Maven Central](https://search.maven.org/), the staging repository [created and +closed earlier](/release-procedures-part2/#staging-maven) needs to be +explicitly released using [Apache's Nexus +instance](https://repository.apache.org/). Doing this involves simply selecting +the repository, clicking the "release" button, and typing a reasonable log +message noting the release. + +Note that it may take a day or so for Maven Central to contain the new +artifacts, just like the mirrors, but absence of artifacts from Maven Central +does not block announcement of the release as long as they are confirmed to be +present on <https://repository.apache.org/>. + +### Docker images + +Both the `guacamole/guacamole` and `guacamole/guacd` images should now be +updated with a new version-specific tag, duplicated to the `latest` tag. Since +the images deployed for past release candidates were first cleaned with +`git clean`, nothing should be actually rebuilt as a consequence of running +`docker build` unless something has gone wrong and source changes were made +in the absence of an RC. + +For example, to build the `guacamole/guacamole` Docker image for the current +release candidate, from within the top-level `incubator-guacamole-client` +directory: + + $ git clean -xfd . + $ sudo docker build -t guacamole/guacamole:0.9.11-incubating . + $ sudo docker build -t guacamole/guacamole:latest . + +Each of the above commands should finish virtually instantaneously, and the +hash of the built images should match each other and the previous RC. Assuming +all looks well, it should be safe to push the images: + + $ sudo docker push guacamole/guacamole:0.9.11-incubating + $ sudo docker push guacamole/guacamole:latest + +Again, this should finish virtually instantaneously, as no new data will need +to be pushed. Docker Hub already has the images/layers from the previous RC +builds. + http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/20dc7f6b/release-procedure-part4.md ---------------------------------------------------------------------- diff --git a/release-procedure-part4.md b/release-procedure-part4.md new file mode 100644 index 0000000..cc43c6e --- /dev/null +++ b/release-procedure-part4.md @@ -0,0 +1,97 @@ +--- +layout: page +title: Announcing the release +permalink: /release-procedures-part4/ +--- + +* Table of contents +{:toc} + +Update website announcing the release {#update-website} +------------------------------------------------------- + +Once the full 24 hours has elapsed since [the final release artifacts were +uploaded](/release-procedures-part3/#final-upload), the website must be updated +to point to the new release. There are three specific things which must be +updated: + +1. The top-level symbolic links within `/doc` must be updated to point to the + documentation of the latest release. + +2. The `released: false` field at the top of the release notes needs to be + updated to `released: true` to allow the release to be listed with the rest + in the [release archives](/releases/). The `date` field should also be + updated to note the actual date and time of release. + +3. The `artifact-root`, `checksum-root`, and `download-path` must be updated + to use the release directory (rather than the RC directory) and to *not* + use `dist.apache.org`. + +Example: [the pull request for incubator-guacamole-website announcing 0.9.11-incubating](https://github.com/apache/incubator-guacamole-website/pull/31) + +Update JIRA version information {#update-jira} +---------------------------------------------- + +JIRA must be updated as well, as each version is listed for the sake of tagging +issues. At this point, there should already be a version created for the recent +release, but it will not be marked as released. Mark the version as "released" +within JIRA, making sure a version number for the next release has been created +as a placeholder: + +<https://issues.apache.org/jira/plugins/servlet/project-config/GUACAMOLE/versions> + +Email announcement {#email-announce} +------------------------------------ + +Finally, send an email with the subject `[ANNOUNCE] Apache Guacamole [VERSION] +released` to <[email protected]>, <[email protected]>, +<[email protected]>, and +<[email protected]>. **This email MUST be sent from an +apache.org email address**, and should contain an announcement like the +following: + +``` +The Apache Guacamole community is proud to announce the release of Apache +Guacamole [VERSION]. + +Apache Guacamole (incubating) is a clientless remote desktop gateway which +supports standard protocols like VNC, RDP, and SSH. We call it "clientless" +because no plugins or client software are required; once Guacamole is +installed on a server, all you need to access your desktops is a web +browser. + +[VERSION] features [RELEASE HIGHLIGHTS]. + +A full list of the changes in this release, along with links to downloads +and updated documentation, can be found in the release notes: + +http://guacamole.incubator.apache.org/releases/[VERSION]/ + +For more information on Apache Guacamole, please see: + +http://guacamole.incubator.apache.org/ + +Thanks! + +The Apache Guacamole (incubating) Community + +---- + +DISCLAIMER: + +Apache Guacamole is an effort undergoing Incubation at The Apache Software +Foundation (ASF), sponsored by the Incubator. Incubation is required of all +newly accepted projects until a further review indicates that the +infrastructure, communications, and decision making process have stabilized +in a manner consistent with other successful ASF projects. While incubation +status is not necessarily a reflection of the completeness or stability of +the code, it does indicate that the project has yet to be fully endorsed by +the ASF. +``` + +Where `[VERSION]` is the version that was just released and `[RELEASE +HIGHLIGHTS]` is a brief description of the key features, improvements, and bug +fixes of the release. + +Example: [the 0.9.10-incubating announcement email](http://mail-archives.apache.org/mod_mbox/www-announce/201612.mbox/%3CCALKeL-PxDiixdCkpLcVE9XN07aRUVx1aPR%3D5ysaAJjKdU1ZnNg%40mail.gmail.com%3E) +
