guacamole-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [2/3] incubator-guacamole-website git commit: Document pull request procedures.
Date Fri, 17 Feb 2017 17:20:37 GMT
Document pull request procedures.


Branch: refs/heads/master
Commit: 02dcc9dc60c8d67adf880023f43b99e316bc74a7
Parents: 8e2b709
Author: Michael Jumper <>
Authored: Sun Feb 12 11:41:20 2017 -0800
Committer: Michael Jumper <>
Committed: Thu Feb 16 23:40:05 2017 -0800

----------------------------------------------------------------------   |   5 ++- | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 114 insertions(+), 2 deletions(-)
diff --git a/ b/
index fe89908..004529c 100644
--- a/
+++ b/
@@ -89,14 +89,15 @@ of the [Apache Guacamole PPMC](#ppmc-members).
 Committers have write access to Apache Guacamole's git repositories, but do not
 make direct changes on their own behalf. Code changes are made only through
-pull requests, and are merged only after code review by a committer not
-otherwise directly involved in those changes.
+[pull requests](/pull-requests/), and are merged only after code review by
+a committer not otherwise directly involved in those changes.
 ### Resources for committers:
 * [Committers' FAQ](
 * [Guide for new committers](
 * [Maintaining the website](
+* [Managing pull requests](/pull-requests/)
 * [Style guidelines](/guac-style/)
 PPMC members
diff --git a/ b/
new file mode 100644
index 0000000..2fec30b
--- /dev/null
+++ b/
@@ -0,0 +1,111 @@
+layout: page 
+title: Managing Pull Requests
+permalink: /pull-requests/
+The Apache Guacamole project requires code review for absolutely all changes,
+and uses pull requests to facilitate that review. However, because pull 
+requests must be made against the read-only mirrors on GitHub, merging is
+slightly more complicated.
+There is no "merge" button. Merges must be performed manually and pushed to the
+main repositories which live at the ASF. Once pushed, a robot running at the
+ASF (which has write access to the GitHub mirrors) will automatically close
+the pull request as merged.
+You will need three remotes for each Apache Guacamole git repository:
+1. The upstream repository hosted by the ASF's servers
+2. The GitHub mirror
+3. Your personal fork of the GitHub mirror
+For the sake of simplicity, these will be referred to here as `upstream`,
+`mirror`, and `origin`, respectively. For example, the recommended
+configuration for `incubator-guacamole-server` would be:
+    $ git remote -v
+    mirror
+    origin
+    upstream
+    $
+After reviewing and approving code submitted via a pull request, you will need
+1. Manually fetch the contents of the pull request to a new branch via the
+   command line:
+       $ git fetch mirror pull/NUMBER/head:some-branch
+   where `NUMBER` is the pull request number and `some-branch` is a sensible
+   branch name of your choice.
+2. Ensure your copy of the base branch is up to date, whether that be `master`
+   or the staging branch for an upcoming release:
+       $ git fetch upstream
+       $ git checkout master
+       $ git merge --ff-only upstream/master
+       $ git push origin
+3. Merge the branch containing the changes from the pull request:
+       $ git merge --no-ff some-branch
+   **Be sure to specify `--no-ff`!** Merges of pull requests must have
+   corresponding merge commits, and the messages of those merge commits must
+   properly tag the associated JIRA issue (just like all other commits).
+4. Confirm that the changes look as expected:
+       $ git diff upstream/master
+5. Push the merge result to the ASF repository:
+       $ git push upstream master
+   You will be prompted for your username (Apache ID) and password. It is
+   highly recommended that you not save/cache your credentials for this step,
+   as it serves as an additional sanity check preventing accidental pushes to
+   the main repository.
+Once this is done, the ASF git bot should kick in, and emails should go out
+across the <> list noting each commit
+pushed. If this does not happen, or the commits show up only within the ASF
+repositories and not the GitHub mirrors, it may be necessary to reach out to
+[Infra]( by opening an issue
+against [the "Infrastructure" project in
+Merging release-specific changes
+When a pull request is intended for a pending release, the merge base specified
+in the pull request *should* be the staging branch for that release. That said,
+part of the point of code review is to identify mistakes prior to merge, and
+using the wrong base for a release-specific change is one of those mistakes. It
+is good practice to verify whether a staging branch for the release exists in
+the main ASF repository, and to double-check whether the change in question is
+associated with a release-specific change by checking the "Fix Version" field
+for the issue in JIRA.
+Merging release-specific changes involves:
+1. Merging the pull request to the **staging branch**. The steps for doing this
+   are exactly as described above, except you will need to specify
+   `staging/VERSION` instead of `master`.
+2. Merging the **staging branch** to **`master`**. Doing this is largely the
+   same as described above, except that there is inherently no JIRA issue to
+   tag in the commit message. A message like "Merging 0.9.10-incubating
+   changes back to master." is pretty sensible.
+   the staging branch to master rather than the pull request is to ensure that
+   the git history reflects that all commits to the staging branch are present
+   on `master`. If the pull request is merged to master directly, then the git
+   history ends up with two distinct merges and two distinct sets of commits,
+   and final release sanity checks performed prior to deleting the staging
+   branch will fail.

View raw message