GNOME.org
 

[bugzilla-gnome-org-extensions] Add a Help page

commit 533b273789d11bde9910c0ef3c5ba727990c6c4a
Author: Owen W. Taylor <otaylor fishsoup net>
Date:   Sun Oct 4 22:19:32 2009 -0400

    Add a Help page
    
    Add help.html and link to it at the bottom of the page. The URL
    to the help page is another config setting, since it differs depending
    on proxy vs. Bugzilla extension.

 Makefile                                           |    1 +
 .../en/default/pages/splinter.html.tmpl.in         |    1 +
 js/splinter.js                                     |   16 ++-
 proxy/splinter_proxy.py                            |    1 +
 web/help.html                                      |  145 ++++++++++++++++++++
 web/index.html.body                                |    4 +
 web/splinter.css                                   |    6 +
 7 files changed, 170 insertions(+), 4 deletions(-)
---
diff --git a/Makefile b/Makefile
index fe0c31b..ea63677 100644
--- a/Makefile
+++ b/Makefile
@@ -33,6 +33,7 @@ CLEAN_FILES =                                 \
        web/splinter.flat.js
 
 WEB_FILES =                                    \
+       web/help.html                           \
        web/index.html                          \
        web/jquery.min.js                       \
        web/splinter.css                        \
diff --git a/extension/template/en/default/pages/splinter.html.tmpl.in 
b/extension/template/en/default/pages/splinter.html.tmpl.in
index 06c9d3d..d2e1018 100644
--- a/extension/template/en/default/pages/splinter.html.tmpl.in
+++ b/extension/template/en/default/pages/splinter.html.tmpl.in
@@ -38,6 +38,7 @@
   $(function() { init(); });
   configBugzillaUrl = '/';
   configHaveExtension = true;
+  configHelp = "/extensions/splinter/web/help.html";
   configNote = '';
 </script>
 
diff --git a/js/splinter.js b/js/splinter.js
index 577308f..1c80aa2 100644
--- a/js/splinter.js
+++ b/js/splinter.js
@@ -27,12 +27,18 @@ var currentEditComment;
 const ADD_COMMENT_SUCCESS = /<title>\s*Bug[\S\s]*processed\s*<\/title>/;
 const UPDATE_ATTACHMENT_SUCCESS = /<title>\s*Changes\s+Submitted/;
 
+function doneLoading() {
+    $("#loading").hide();
+    $("#helpLink").attr("href", configHelp);
+    $("#credits").show();
+}
+
 function displayError(msg) {
     $("<p></p>")
         .text(msg)
         .appendTo("#error");
     $("#error").show();
-    $("#loading").hide();
+    doneLoad();
 }
 
 function updateAttachmentStatus(attachment, newStatus, success, failure) {
@@ -818,7 +824,7 @@ function start(xml) {
 
     document.title = "Attachment " + theAttachment.id + " - " + theAttachment.description + " - Patch 
Review";
 
-    $("#loading").hide();
+    doneLoading();
     $("#attachmentInfo").show();
     $("#navigation").show();
     $("#overview").show();
@@ -992,7 +998,7 @@ function showEnterBug() {
                                var newBugId = Utils.strip($("#enterBugInput").val());
                                document.location = newPageUrl(newBugId);
                            });
-    $("#loading").hide();
+    doneLoading();
     $("#enterBug").show();
 
     if (!reviewStorage)
@@ -1043,6 +1049,8 @@ function showChooseAttachment() {
     document.title = "Bug " + theBug.id + " - " + theBug.shortDesc + " - Patch Review";
     $("#originalBugLink").attr('href', configBugzillaUrl + "/show_bug.cgi?id=" + theBug.id);
 
+    $("#allReviewsLink").attr('href', configBase);
+
     var drafts = {};
     var published = {};
     if (reviewStorage) {
@@ -1099,7 +1107,7 @@ function showChooseAttachment() {
             .appendTo("#chooseAttachment tbody");
     }
 
-    $("#loading").hide();
+    doneLoading();
     $("#chooseAttachment").show();
 }
 
diff --git a/proxy/splinter_proxy.py b/proxy/splinter_proxy.py
index e70c0d7..7c071ea 100755
--- a/proxy/splinter_proxy.py
+++ b/proxy/splinter_proxy.py
@@ -401,6 +401,7 @@ configAttachmentStatuses = [
 configBase = 'index.html';
 configBugzillaUrl = '%(bugzilla_url)s';
 configHaveExtension = %(have_extension)s;
+configHelp = 'help.html';
 configNote = '%(note)s';
 """ % {
         'bugzilla_url': current_config['bugzilla_url'],
diff --git a/web/help.html b/web/help.html
new file mode 100644
index 0000000..a6409cc
--- /dev/null
+++ b/web/help.html
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
+  <head>
+    <title>Help - Splinter Patch Review</title>
+    <style type="text/css">
+body {
+    max-width: 60em;
+    margin-left: auto;
+    margin-right: auto;
+    padding-left: 1em;
+    padding-right: 1em;
+}
+    </style>
+  </head>
+  <body>
+    <h2>Splinter Patch Review</h2>
+    <p>
+      Splinter is an add-on for Bugzilla to allow conveniently
+      reviewing patches that people have attached to
+      Bugzilla. <a href="http://fishsoup.net/software/splinter";>More
+      information about Splinter</a>.
+    </p>
+    <h3>The patch review view</h3>
+    <p>
+      If you get to Splinter by clicking on a link next to an
+      attachment in Bugzilla, you are presented with the patch
+      review view. This view has a number of different pages that can
+      be switched between with the links at the top of the screen.
+      The first page is the Overview page, the other pages correspond to
+      individual files changed by the review.
+    </p>
+    <p>
+      On the Overview page, from top to bottom are shown:
+    </p>
+    <ul>
+      <li>Introductory text to the patch. For a patch that was created
+      using 'git format-patch' this will be the Git commit
+      message.</li>
+      <li>Controls for creating a new review</li>
+      <li>Previous reviews that other people have written.</li>
+    </ul>
+    <p>
+      The pages for each file show a two-column view of the changes.
+      The left column is the previous contents of the file,
+      the right column is the new contents of the file. (If the file
+      is an entirely new file or an entirely deleted file, only one
+      column will be shown.) Red indicates lines that have been
+      removed, green lines that have been added, and blue lines that
+      were modified.
+    </p>
+    <p>
+      If people have previously made comments on individual lines of
+      the patch, they will show up both summarized on the Overview
+      page and also inline when looking at the files of the patch.
+    </p>
+    <h3>Reviewing an existing patch</h3>
+    <p>
+      There are three components to a review:
+    </p>
+    <ul>
+      <li>
+       An overall comment. The text area on the first page allows
+       you to enter your overall thoughts on the bug.
+      </li>
+      <li>
+       Detailed comments on changes within the files. To comment on a
+       line in a patch, double click on it, and a text area will open
+       beneath that comment. When you are done, click the Save button
+       to save your comment or the Cancel button to throw your
+       comment away. You can double-click on a saved comment to start
+       editing it again and make further changes.
+      </li>
+      <li>
+       A change to the attachment status. (This is specific to
+       Bugzilla instances that have attachment status, which is a
+       non-upstream patch. It's somewhat similar to attachment flags,
+       which splinter doesn't currently support displaying or
+       changing.) This allows you to mark a patch as read to commit
+       or needing additional work. This is done by changing the
+       drop-down next to the Publish button.
+      </li>
+    </ul>
+    <p>
+      Once you are done writing your review, go back to Overview page
+      and click the "Publish" button to submit it as a comment on the
+      bug. The comment will have a link back to the review page so
+      that people can see your comments with the full context.
+    </p>
+    <h3>Saved drafts</h3>
+    <p>
+      Whenever you start making changes, a draft is automatically
+      saved. If you come back to the patch review page for the same
+      attachment, that draft will automatically be resumed. Drafts are
+      not visible to anybody else until published.
+    </p>
+    <p>
+      Note that saving drafts requires the your browser to have support
+      for the "DOM Storage" standard. At time of writing, this is
+      available only in a few very recent browsers, like Firefox
+      3.5. Strict privacy protections like disabling cookies may also
+      disable DOM Storage, since it provides another mechanism for
+      sites to track information about their users.
+    </p>
+    <h3>Responding to someone's review</h3>
+    <p>
+      A response is treated just like any other review and created the
+      same way. A couple of features are helpful when responding: you
+      can double-click on an inline comment to respond to it. And on
+      the overview page, when you click on a detailed comment, you are
+      taken directly to the original location of the comment.
+    </p>
+    <h3>Uploading patches for review</h3>
+    <p>
+      Splinter doesn't really care how patches are provided to
+      Bugzilla, as long as they are well-formatted patches. If you are
+      using Git for version control, you can either format changes as
+      patches
+      using <a href="http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html";>'git
+      format-patch</a> and attach them manually to the bug, or you
+      can
+      use <a href="http://fishsoup.net/software/git-bz";>git-bz</a>.
+      git-bz is highly recommended; it automates most of the steps
+      that Splinter can't handle: it files new bugs, attaches updated
+      attachments to existing bugs, and closes bugs when you push the
+      corresponding git commits to your central repository.
+    </p>
+    <h3>The bug review view</h3>
+    <p>
+      Splinter also has a view where it shows all patches attached to
+      the bug with their status and links to review them. You are
+      taken to this page after publishing a review. You can also get
+      to this page with the bug link in the upper-right corner of the
+      patch review view.
+    </p>
+    <h3>Your reviews</h3>
+    <p>
+      Splinter can also show you a list of all your draft and
+      published reviews. Access this page with the "Your reviews"
+      link at the bottom of the bug review view. In-progress drafts
+      are shown in bold.
+    </p>
+  </body>
+</html>
diff --git a/web/index.html.body b/web/index.html.body
index 964a640..b2da8fd 100644
--- a/web/index.html.body
+++ b/web/index.html.body
@@ -61,4 +61,8 @@
   </div>
 </div>
 <div id="files" style="display: none;"></div>
+<div id="credits" style="display: none;">
+  Powered by <a href="http://fishsoup.net/software/splinter";>Splinter</a> |
+  <a id='helpLink' target='splinterHelp'>Help</a>
+</div>
 <div id="saveDraftNotice" style="display: none;"></div>
diff --git a/web/splinter.css b/web/splinter.css
index 55ffb4b..346297d 100644
--- a/web/splinter.css
+++ b/web/splinter.css
@@ -398,6 +398,12 @@ div.review-patch-comment-text {
     right: 0px;
 }
 
+#credits {
+    font-size: 80%;
+    color: #888888;
+    text-align: center;
+}
+
 /* dialog.js */
 
 #modalContainer {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]