hbase-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject git commit: HBASE-11539 Expand info about contributing to and building documentation (Misty Stanley-Jones)
Date Fri, 01 Aug 2014 02:54:09 GMT
Repository: hbase
Updated Branches:
  refs/heads/master 1326d329e -> 33e141810

HBASE-11539 Expand info about contributing to and building documentation (Misty Stanley-Jones)

Project: http://git-wip-us.apache.org/repos/asf/hbase/repo
Commit: http://git-wip-us.apache.org/repos/asf/hbase/commit/33e14181
Tree: http://git-wip-us.apache.org/repos/asf/hbase/tree/33e14181
Diff: http://git-wip-us.apache.org/repos/asf/hbase/diff/33e14181

Branch: refs/heads/master
Commit: 33e141810558f665e8336bb594303420d669f686
Parents: 1326d32
Author: stack <stack@apache.org>
Authored: Thu Jul 31 19:53:58 2014 -0700
Committer: stack <stack@apache.org>
Committed: Thu Jul 31 19:53:58 2014 -0700

 .../appendix_contributing_to_documentation.xml  | 403 +++++++++++++++++++
 src/main/docbkx/book.xml                        |   3 +-
 src/main/docbkx/preface.xml                     |  32 +-
 3 files changed, 428 insertions(+), 10 deletions(-)

diff --git a/src/main/docbkx/appendix_contributing_to_documentation.xml b/src/main/docbkx/appendix_contributing_to_documentation.xml
new file mode 100644
index 0000000..080525a
--- /dev/null
+++ b/src/main/docbkx/appendix_contributing_to_documentation.xml
@@ -0,0 +1,403 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<appendix version="5.0" xml:id="appendix_contributing_to_documentation"
+    xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+    xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg"
+    xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml"
+    xmlns:db="http://docbook.org/ns/docbook">
+    <!--
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+    <title>Contributing to Documentation</title>
+    <para>The Apache HBase project welcomes contributions to all aspects of the project,
+        the documentation. In HBase, documentation includes the following areas, and probably
+        others:</para>
+    <itemizedlist>
+        <listitem>
+            <para>The <link xlink:href="http://hbase.apache.org/book.html">HBase
+                    Guide</link> (this book)</para>
+        </listitem>
+        <listitem>
+            <para>The <link xlink:href="http://hbase.apache.org/">HBase website</link>e</para>
+        </listitem>
+        <listitem>
+            <para>The <link xlink:href="http://wiki.apache.org/hadoop/Hbase">HBase
+                Wiki</link></para>
+        </listitem>
+        <listitem>
+            <para>API documentation</para>
+        </listitem>
+        <listitem>
+            <para>Command-line utility output and help text</para>
+        </listitem>
+        <listitem>
+            <para>Web UI strings, explicit help text, context-sensitive strings, and
+        </listitem>
+        <listitem>
+            <para>Log messages</para>
+        </listitem>
+        <listitem>
+            <para>Comments in source files, configuration files, and others</para>
+        </listitem>
+        <listitem>
+            <para>Localization of any of the above into target languages other than
+        </listitem>
+    </itemizedlist>
+    <para>No matter which area you want to help out with, the first step is almost
always to
+        download (typically by cloning the Git repository) and familiarize yourself with
the HBase
+        source code. The only exception in the list above is the HBase Wiki, which is edited
+        For information on downloading and building the source, see <xref linkend="developer"
+        />.</para>
+    <section>
+        <title>Getting Access to the Wiki</title>
+        <para>The HBase Wiki is not well-maintained and much of its content has been
moved into the
+            HBase Reference Guide (this guide). However, some pages on the Wiki are well
+            and it would be great to have some volunteers willing to help out with the Wiki.
+            request access to the Wiki, register a new account at <link
+                xlink:href="https://wiki.apache.org/hadoop/Hbase?action=newaccount"
+                >https://wiki.apache.org/hadoop/Hbase?action=newaccount</link>.
Contact one of the
+            HBase committers, who can either give you access or refer you to someone who
+    </section>
+    <section>
+        <title>Contributing to Documentation or Other Strings</title>
+        <para> If you spot an error in a string in a UI, utility, script, log message,
or elsewhere,
+            or you think something could be made more clear, or you think text needs to be
+            where it doesn't currently exist, the first step is to file a JIRA. Be sure to
set the
+            component to <literal>Documentation</literal> in addition any other
involved components.
+            Most components have one or more default owners, who monitor new issues which
come into
+            those queues. Regardless of whether you feel able to fix the bug, you should
still file
+            bugs where you see them.</para>
+        <para>If you want to try your hand at fixing your newly-filed bug, assign it
to yourself.
+            You will need to clone the HBase Git repository to your local system and work
on the
+            issue there. When you have developed a potential fix, submit it for review. If
+            addresses the issue and is seen as an improvement, one of the HBase committers
+            commit it to one or more branches, as appropriate.</para>
+        <procedure xml:id="submit_doc_patch_procedure">
+            <title>Suggested Work flow for Submitting Patches</title>
+            <para>This procedure goes into more detail than Git pros will need, but
is included in
+                this appendix so that people unfamiliar with Git can feel confident contributing
+                HBase while they learn.</para>
+            <step>
+                <para>If you have not already done so, clone the Git repository locally.
You only
+                    need to do this once.</para>
+            </step>
+            <step>
+                <para>Fairly often, pull remote changes into your local repository
by using the
+                        <code>git pull</code> command, while your master branch
is checked
+                    out.</para>
+            </step>
+            <step>
+                <para>For each issue you work on, create a new branch. One convention
that works
+                    well for naming the branches is to name a given branch the same as the
+                    relates to:</para>
+                <screen>$ git checkout -b HBASE-123456</screen>
+            </step>
+            <step>
+                <para>Make your suggested changes on your branch, committing your changes
to your
+                    local repository often. If you need to switch to working on a different
+                    remember to check out the appropriate branch.</para>
+            </step>
+            <step>
+                <para>When you are ready to submit your patch, first be sure that HBase
+                    cleanly and behaves as expected in your modified branch. If you have
+                    documentation changes, be sure the documentation and website builds.</para>
+                <note>
+                    <para>Before you use the <literal>site</literal> target
the very first time, be
+                        sure you have built HBase at least once, in order to fetch all the
+                        dependencies you need.</para>
+                </note>
+                <screen>$ mvn clean install -DskipTests               # Builds HBase</screen>
+                <screen>$ mvn clean site -DskipTests                  # Builds the
website and documentation</screen>
+                <para>If any errors occur, address them.</para>
+            </step>
+            <step>
+                <para>If it takes you several days or weeks to implement your fix,
or you know that
+                    the area of the code you are working in has had a lot of changes lately,
+                    sure you rebase your branch against the remote master and take care of
+                    conflicts before submitting your patch.</para>
+                <screen>
+$ git checkout HBASE-123456
+$ git rebase origin/master                
+                </screen>
+            </step>
+            <step>
+                <para>Generate your patch against the remote master. Run the following
command from
+                    the top level of your git repository (usually called
+                    <literal>hbase</literal>):</para>
+                <screen>$ git diff --no-prefix origin/master > HBASE-123456.patch</screen>
+                <para>The name of the patch should contain the JIRA ID. Look over the
patch file to
+                    be sure that you did not change any additional files by accident and
that there
+                    are no other surprises. When you are satisfied, attach the patch to the
JIRA and
+                    click the <guibutton>Patch Available</guibutton> button.
A reviewer
+                    will review your patch. If you need to submit a new version of the patch,
+                    the old one on the JIRA and add a version number to the name of the new
+                    patch.</para>
+            </step>
+            <step>
+                <para>After a change has been committed, there is no need to keep your
local branch
+                    around. Instead you should run <command>git pull</command>
to get the new change
+                    into your master branch.</para>
+            </step>
+        </procedure>
+    </section>
+    <section>
+        <title>Editing the HBase Website</title>
+        <para>The source for the HBase website is in the HBase source, in the
+                <filename>src/main/site/</filename> directory. Within this directory,
source for the
+            individual pages is in the <filename>xdocs/</filename> directory,
and images referenced
+            in those pages are in the <filename>images/</filename> directory.
This directory also
+            stores images used in the HBase Reference Guide.</para>
+        <para>The website's pages are written in an HTML-like XML dialect called xdoc,
which has a
+            reference guide at <link
+                xlink:href="http://maven.apache.org/archives/maven-1.x/plugins/xdoc/reference/xdocs.html"
+                >http://maven.apache.org/archives/maven-1.x/plugins/xdoc/reference/xdocs.html</link>.
+            You can edit these files in a plain-text editor, an IDE, or an XML editor such
+            XML Mind XML Editor (XXE) or Oxygen XML Author. </para>
+        <para>To preview your changes, build the website using the <command>mvn
clean site
+                -DskipTests</command> command. The HTML output resides in the
+                <filename>target/site/</filename> directory. When you are satisfied
with your
+            changes, follow the procedure in <xref linkend="submit_doc_patch_procedure"/>
to submit
+            your patch.</para>
+    </section>
+    <section>
+        <title>Editing the HBase Reference Guide</title>
+        <para>The source for the HBase Reference Guide is in the HBase source, in the
+                <filename>src/main/docbkx/</filename> directory. It is written
in <link
+                xlink:href="http://www.docbook.org/">Docbook</link> XML. Docbook
can be
+            intimidating, but you can typically follow the formatting of the surrounding
file to get
+            an idea of the mark-up. You can edit Docbook XML files using a plain-text editor,
+            XML-aware IDE, or a specialized XML editor.</para>
+        <para>Docbook's syntax can be picky. Before submitting a patch, be sure to
build the output
+            locally using the <command>mvn site</command> command. If you do
not get any build
+            errors, that means that the XML is well-formed, which means that each opening
tag is
+            balanced by a closing tag. Well-formedness is not exactly the same as validity.
+            the output in <filename>target/docbkx/</filename> for any surprises
before submitting a
+            patch.</para>
+    </section>
+    <section>
+        <title>Auto-Generated Content</title>
+        <para>Some parts of the HBase Reference Guide, most notably <xref linkend="config.files"/>,
+            are generated automatically, so that this area of the documentation stays in
sync with
+            the code. This is done by means of an XSLT transform, which you can examine in
+            source at <filename>src/main/xslt/configuration_to_docbook_section.xsl</filename>.
+            transforms the <filename>hbase-common/src/main/resources/hbase-default.xml</filename>
+            file into a Docbook output which can be included in the Reference Guide. Sometimes,
+            is necessary to add configuration parameters or modify their descriptions. Make
+            modifications to the source file, and they will be included in the Reference
Guide when
+            it is rebuilt.</para>
+        <para>It is possible that other types of content can and will be automatically
+            from HBase source files in the future.</para>
+    </section>
+    <section>
+        <title>Multi-Page and Single-Page Output</title>
+        <para>You can examine the <literal>site</literal> target in the
+                <filename>pom.xml</filename> file included at the top level of
the HBase source for
+            details on the process of building the website and documentation. The Reference
Guide is
+            built twice, once as a single-page output and once with one HTML file per chapter.
+            single-page output is located in <filename>target/docbkx/book.html</filename>,
while the
+            multi-page output's index page is at <filename>target/docbkx/book/book.html</filename>.
+            Each of these outputs has its own <filename>images/</filename> and
+                <filename>css/</filename> directories, which are created at build
+    </section>
+    <section>
+        <title>Images in the HBase Reference Guide</title>
+        <para>You can include images in the HBase Reference Guide. For accessibility
reasons, it is
+            recommended that you use a &lt;figure&gt; Docbook element for an image.
This allows
+            screen readers to navigate to the image and also provides alternative text for
+            image. The following is an example of a &lt;figure&gt; element.</para>
+        <programlisting><![CDATA[<figure>
+  <title>HFile Version 1</title>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="timeline_consistency.png" />
+    </imageobject>
+    <textobject>
+      <phrase>HFile Version 1</phrase>
+    </textobject>
+  </mediaobject>
+        </programlisting>
+        <para>The &lt;textobject&gt; can contain a few sentences describing
the image, rather than
+            simply reiterating the title. You can optionally specify alignment and size options
+            the &lt;imagedata&gt; element.</para>
+        <para>When doing a local build, save the image to the
+                <filename>src/main/site/resources/images/</filename> directory.
In the
+            &lt;imagedata&gt; element, refer to the image as above, with no directory
component. The
+            image will be copied to the appropriate target location during the build of the
+            output.</para>
+        <para>When you submit a patch which includes adding an image to the HBase Reference
+            attach the image to the JIRA. If the committer asks where the image should be
+            it should go into the above directory.</para>
+    </section>
+    <section>
+        <title>Adding a New Chapter to the HBase Reference Guide</title>
+        <para>If you want to add a new chapter to the HBase Reference Guide, the easiest
way is to
+            copy an existing chapter file, rename it, and change the ID and title elements
near the
+            top of the file. Delete the existing content and create the new content. Then
open the
+                <filename>book.xml</filename> file, which is the main file for
the HBase Reference
+            Guide, and use an &lt;xi:include&gt; element to include your new chapter
in the
+            appropriate location. Be sure to add your new file to your Git repository before
+            creating your patch. Note that the <filename>book.xml</filename>
file currently contains
+            many chapters. You can only include a chapter at the same nesting levels as the
+            chapters in the file. When in doubt, check to see how other files have been
+            included.</para>
+    </section>
+    <section>
+        <title>Docbook Common Issues</title>
+        <para>The following Docbook issues come up often. Some of these are preferences,
but others
+            can create mysterious build errors or other problems.</para>
+        <qandaset>
+            <qandaentry>
+                <question>
+                    <para>What can go where?</para>
+                </question>
+                <answer>
+                    <para>There is often confusion about which child elements are valid
in a given
+                        context. When in doubt, <link
+                            xlink:href="http://docbook.org/tdg/en/html/docbook.html">Docbook:
+                            Definitive Guide</link> is the best resource. It has an
appendix which
+                        is indexed by element and contains all valid child and parent elements
+                        any given element. If you edit Docbook often, a schema-aware XML
+                        makes things easier.</para>
+                </answer>
+            </qandaentry>
+            <qandaentry>
+                <question>
+                    <para>Paragraphs and Admonitions</para>
+                </question>
+                <answer>
+                    <para>It is a common pattern, and it is technically valid, to put
an admonition
+                        such as a &lt;note&gt; inside a &lt;para&gt; element.
Because admonitions
+                        render as block-level elements (they take the whole width of the
page), it
+                        is better to mark them up as siblings to the paragraphs around them,
+                        this:</para>
+                    <programlisting><![CDATA[<para>This is the paragraph.</para>
+    <para>This is an admonition which occurs after the paragraph.</para>
+                </answer>
+            </qandaentry>
+            <qandaentry>
+                <question>
+                    <para>Wrap textual &lt;listitem&gt; and &lt;entry&gt;
contents in &lt;para&gt;
+                        elements.</para>
+                </question>
+                <answer>
+                    <para>Because the contents of a &lt;listitem&gt; (an element
in an itemized,
+                        ordered, or variable list) or an &lt;entry&gt; (a cell in
a table) can
+                        consist of things other than plain text, they need to be wrapped
in some
+                        element. If they are plain text, they need to be inclosed in &lt;para&gt;
+                        tags. This is tedious but necessary for validity.</para>
+                    <programlisting><![CDATA[<itemizedlist>
+    <listitem>
+        <para>This is a paragraph.</para>
+    </listitem>
+    <listitem>
+        <screen>This is screen output.</screen>
+    </listitem>
+                </answer>
+            </qandaentry>
+            <qandaentry>
+                <question>
+                    <para>When to use &lt;command&gt;, &lt;code&gt;,
+                        &lt;screen&gt;</para>
+                </question>
+                <answer>
+                    <para>The first two are in-line tags, which can occur within the
flow of
+                        paragraphs or titles. The second two are block elements.</para>
+                    <para>Use &lt;command&gt; to mention a command such as
+                            shell</command> in the flow of a sentence. Use &lt;code&gt;
for other
+                        inline text referring to code. Incidentally, use &lt;literal&gt;
to specify
+                        literal strings that should be typed or entered exactly as shown.
Within a
+                        &lt;screen&gt; listing, it can be helpful to use the &lt;userinput&gt;
+                        &lt;computeroutput&gt; elements to mark up the text further.</para>
+                    <para>Use &lt;screen&gt; to display input and output as
the user would
+                            <emphasis>see</emphasis> it on the screen, in a log
file, etc. Use
+                        &lt;programlisting&gt; only for blocks of code that occur
within a file,
+                        such as Java or XML code, or a Bash shell script.</para>
+                </answer>
+            </qandaentry>
+            <qandaentry>
+                <question>
+                    <para>How to escape XML elements so that they show up as XML</para>
+                </question>
+                <answer>
+                    <para>For one-off instances or short in-line mentions, use the
&amp;lt; and
+                        &amp;gt; encoded characters. For longer mentions, or blocks of
code, enclose
+                        it with <![CDATA[&lt;![CDATA[]]&gt;]]>, which is much
easier to maintain and
+                        parse in the source files..</para>
+                </answer>
+            </qandaentry>
+            <qandaentry>
+                <question>
+                    <para>Tips and tricks for making screen output look good</para>
+                </question>
+                <answer>
+                    <para>Text within &lt;screen&gt; and &lt;programlisting&gt;
elements is shown
+                        exactly as it appears in the source, including indentation, tabs,
and line
+                        wrap.</para>
+                    <itemizedlist>
+                        <listitem>
+                            <para>Indent the starting and closing XML elements, but
do not indent
+                                the content. Also, to avoid having an extra blank line at
+                                beginning of the programlisting output, do not put the CDATA
+                                element on its own line. For example:</para>
+                            <programlisting><![CDATA[        <programlisting>
+case $1 in
+  --cleanZk|--cleanHdfs|--cleanAll)
+    matches="yes" ;;
+  *) ;;
+        </programlisting>]]></programlisting>
+                        </listitem>
+                        <listitem>
+                            <para>After pasting code into a programlisting, fix the
+                                manually, using two <emphasis>spaces</emphasis>
per desired
+                                indentation. For screen output, be sure to include line breaks
+                                that the text is no longer than 100 characters.</para>
+                        </listitem>
+                    </itemizedlist>
+                </answer>
+            </qandaentry>
+            <qandaentry>
+                <question>
+                    <para>Isolate Changes for Easy Diff Review.</para>
+                </question>
+                <answer>
+                    <para>Be careful with pretty-printing or re-formatting an entire
XML file, even
+                        if the formatting has degraded over time. If you need to reformat
a file, do
+                        that in a separate JIRA where you do not change any content. Be careful
+                        because some XML editors do a bulk-reformat when you open a new file,
+                        especially if you use GUI mode in the editor.</para>
+                </answer>
+            </qandaentry>
+        </qandaset>
+    </section>
\ No newline at end of file

diff --git a/src/main/docbkx/book.xml b/src/main/docbkx/book.xml
index 2a2e994..0564354 100644
--- a/src/main/docbkx/book.xml
+++ b/src/main/docbkx/book.xml
@@ -4442,7 +4442,8 @@ if (result.isStale()) {
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="developer.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="zookeeper.xml" />
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="community.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="appendix_contributing_to_documentation.xml"
 <appendix xml:id="faq">
     <title >FAQ</title>
     <qandaset defaultlabel='qanda'>

diff --git a/src/main/docbkx/preface.xml b/src/main/docbkx/preface.xml
index ff8efb9..5885bfe 100644
--- a/src/main/docbkx/preface.xml
+++ b/src/main/docbkx/preface.xml
@@ -39,15 +39,29 @@
             xlink:href="http://wiki.apache.org/hadoop/Hbase">wiki</link> where the
         information can be found.</para>
-    <para>This reference guide is a work in progress. The source for this guide can
be found at
-            <filename>src/main/docbkx</filename> in a checkout of the hbase project.
This reference
-        guide is marked up using <link
-            xlink:href="http://www.docbook.com/">DocBook</link> from which the the
finished guide is
-        generated as part of the 'site' build target. Run <programlisting>mvn site</programlisting>
-        to generate this documentation. Amendments and improvements to the documentation
-        welcomed. Add a patch to an issue up in the HBase <link
-            xlink:href="https://issues.apache.org/jira/browse/HBASE">JIRA</link>.</para>
+    <formalpara>
+        <title>About This Guide</title>
+        <para>This reference guide is a work in progress. The source for this guide
can be found in
+            the <filename>src/main/docbkx</filename> directory of the HBase source.
This reference
+            guide is marked up using <link xlink:href="http://www.docbook.com/">DocBook</link>
+            which the the finished guide is generated as part of the 'site' build target.
+            <programlisting>mvn site</programlisting> to generate this documentation.
Amendments and
+            improvements to the documentation are welcomed. Click <link
+                xlink:href="https://issues.apache.org/jira/secure/CreateIssueDetails!init.jspa?pid=12310753&amp;issuetype=1&amp;components=12312132&amp;summary=SHORT+DESCRIPTION"
+                >this link</link> to file a new documentation bug against Apache
HBase with some
+            values pre-selected.</para>
+    </formalpara>
+    <formalpara>
+        <title>Contributing to the Documentation</title>
+        <para>For an overview of Docbook and suggestions to get started contributing
to the documentation, see <xref linkend="appendix_contributing_to_documentation" />.</para>
+    </formalpara>
+    <formalpara>
+        <title>Providing Feedback</title>
+        <para>This guide allows you to leave comments or questions on any page, using
Disqus. Look
+            for the Comments area at the bottom of the page. Answering these questions is
+            volunteer effort, and may be delayed.</para>
+    </formalpara>
         <title>Heads-up if this is your first foray into the world of distributed

View raw message