src/main/docbkx/appendix_contributing_to_documentation.xml - hbase - Git at Google

 <?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, including
         the documentation. In HBase, documentation includes the following areas, and probably some
         others:</para>
     <itemizedlist>
         <listitem>
             <para>The <link xlink:href="http://hbase.apache.org/book.html">HBase Reference
                     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 others</para>
         </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 English</para>
         </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 online.
         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 maintained,
             and it would be great to have some volunteers willing to help out with the Wiki. To
             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 can.</para>
     </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 added
             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 it
             addresses the issue and is seen as an improvement, one of the HBase committers will
             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 to
                 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 JIRA it
                     relates to:</para>
                 <screen language="bourne">$ 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 issue,
                     remember to check out the appropriate branch.</para>
             </step>
             <step>
                 <para>When you are ready to submit your patch, first be sure that HBase builds
                     cleanly and behaves as expected in your modified branch. If you have made
                     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 Maven
                         dependencies you need.</para>
                 </note>
                 <screen language="bourne">$ mvn clean install -DskipTests               # Builds HBase</screen>
                 <screen language="bourne">$ 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, make
                     sure you rebase your branch against the remote master and take care of any
                     conflicts before submitting your patch.</para>
                 <screen language="bourne">
 $ 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 language="bourne">$ 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, leave
                     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 as
             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, an
             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. Check
             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 the
             source at <filename>src/main/xslt/configuration_to_docbook_section.xsl</filename>. This
             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, it
             is necessary to add configuration parameters or modify their descriptions. Make the
             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 generated
             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 Maven
                 <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. The
             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 time.</para>
     </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 the
             image. The following is an example of a &lt;figure&gt; element.</para>
         <programlisting language="xml"><![CDATA[<figure>
   <title>HFile Version 1</title>
   <mediaobject>
     <imageobject>
       <imagedata fileref="timeline_consistency.png" />
     </imageobject>
     <textobject>
       <phrase>HFile Version 1</phrase>
     </textobject>
   </mediaobject>
 </figure>]]>
         </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 in
             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 Guide,
             attach the image to the JIRA. If the committer asks where the image should be committed,
             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 other
             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: The
                             Definitive Guide</link> is the best resource. It has an appendix which
                         is indexed by element and contains all valid child and parent elements of
                         any given element. If you edit Docbook often, a schema-aware XML editor
                         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, like
                         this:</para>
                     <programlisting language="xml"><![CDATA[<para>This is the paragraph.</para>
 <note>
     <para>This is an admonition which occurs after the paragraph.</para>
 </note>]]></programlisting>
                 </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 language="xml"><![CDATA[<itemizedlist>
     <listitem>
         <para>This is a paragraph.</para>
     </listitem>
     <listitem>
         <screen>This is screen output.</screen>
     </listitem>
 </itemizedlist>]]></programlisting>
                 </answer>
             </qandaentry>
             <qandaentry>
                 <question>
                     <para>When to use &lt;command&gt;, &lt;code&gt;, &lt;programlisting&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 <command>hbase
                             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; and
                         &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 the
                                 beginning of the programlisting output, do not put the CDATA
                                 element on its own line. For example:</para>
                             <programlisting language="bourne"><![CDATA[        <programlisting>
 case $1 in
   --cleanZk|--cleanHdfs|--cleanAll)
     matches="yes" ;;
   *) ;;
 esac
         </programlisting>]]></programlisting>
                         </listitem>
                         <listitem>
                             <para>After pasting code into a programlisting, fix the indentation
                                 manually, using two <emphasis>spaces</emphasis> per desired
                                 indentation. For screen output, be sure to include line breaks so
                                 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>
             <qandaentry>
                 <question>
                     <para>Syntax Highlighting</para>
                 </question>
                 <answer>
                     <para>The HBase Reference Guide uses the <link
                             xlink:href="http://sourceforge.net/projects/xslthl/files/xslthl/2.1.0/"
                             >XSLT Syntax Highlighting</link> Maven module for syntax highlighting.
                         To enable syntax highlighting for a given &lt;programlisting&gt; or
                         &lt;screen&gt; (or possibly other elements), add the attribute
                                 <literal>language=<replaceable>LANGUAGE_OF_CHOICE</replaceable></literal>
                         to the element, as in the following example:</para>
                     <programlisting language="xml"><![CDATA[
 <programlisting language="xml">
     <foo>bar</foo>
     <bar>foo</bar>
 </programlisting>]]></programlisting>
                     <para>Several syntax types are supported. The most interesting ones for the
                         HBase Reference Guide are <literal>java</literal>, <literal>xml</literal>,
                             <literal>sql</literal>, and <literal>bourne</literal> (for BASH shell
                         output or Linux command-line examples).</para>
                 </answer>
             </qandaentry>
         </qandaset>
     </section>
 </appendix>
	<?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, including
	the documentation. In HBase, documentation includes the following areas, and probably some
	others:</para>
	<itemizedlist>
	<listitem>
	<para>The <link xlink:href="http://hbase.apache.org/book.html">HBase Reference
	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 others</para>
	</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 English</para>
	</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 online.
	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 maintained,
	and it would be great to have some volunteers willing to help out with the Wiki. To
	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 can.</para>
	</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 added
	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 it
	addresses the issue and is seen as an improvement, one of the HBase committers will
	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 to
	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 JIRA it
	relates to:</para>
	<screen language="bourne">$ 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 issue,
	remember to check out the appropriate branch.</para>
	</step>
	<step>
	<para>When you are ready to submit your patch, first be sure that HBase builds
	cleanly and behaves as expected in your modified branch. If you have made
	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 Maven
	dependencies you need.</para>
	</note>
	<screen language="bourne">$ mvn clean install -DskipTests # Builds HBase</screen>
	<screen language="bourne">$ 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, make
	sure you rebase your branch against the remote master and take care of any
	conflicts before submitting your patch.</para>
	<screen language="bourne">
	$ 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 language="bourne">$ 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, leave
	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 as
	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, an
	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. Check
	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 the
	source at <filename>src/main/xslt/configuration_to_docbook_section.xsl</filename>. This
	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, it
	is necessary to add configuration parameters or modify their descriptions. Make the
	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 generated
	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 Maven
	<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. The
	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 time.</para>
	</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 <figure> Docbook element for an image. This allows
	screen readers to navigate to the image and also provides alternative text for the
	image. The following is an example of a <figure> element.</para>
	<programlisting language="xml"><![CDATA[<figure>
	<title>HFile Version 1</title>
	<mediaobject>
	<imageobject>
	<imagedata fileref="timeline_consistency.png" />
	</imageobject>
	<textobject>
	<phrase>HFile Version 1</phrase>
	</textobject>
	</mediaobject>
	</figure>]]>
	</programlisting>
	<para>The <textobject> can contain a few sentences describing the image, rather than
	simply reiterating the title. You can optionally specify alignment and size options in
	the <imagedata> element.</para>
	<para>When doing a local build, save the image to the
	<filename>src/main/site/resources/images/</filename> directory. In the
	<imagedata> 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 Guide,
	attach the image to the JIRA. If the committer asks where the image should be committed,
	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 <xi:include> 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 other
	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: The
	Definitive Guide</link> is the best resource. It has an appendix which
	is indexed by element and contains all valid child and parent elements of
	any given element. If you edit Docbook often, a schema-aware XML editor
	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 <note> inside a <para> 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, like
	this:</para>
	<programlisting language="xml"><![CDATA[<para>This is the paragraph.</para>
	<note>
	<para>This is an admonition which occurs after the paragraph.</para>
	</note>]]></programlisting>
	</answer>
	</qandaentry>
	<qandaentry>
	<question>
	<para>Wrap textual <listitem> and <entry> contents in <para>
	elements.</para>
	</question>
	<answer>
	<para>Because the contents of a <listitem> (an element in an itemized,
	ordered, or variable list) or an <entry> (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 <para>
	tags. This is tedious but necessary for validity.</para>
	<programlisting language="xml"><![CDATA[<itemizedlist>
	<listitem>
	<para>This is a paragraph.</para>
	</listitem>
	<listitem>
	<screen>This is screen output.</screen>
	</listitem>
	</itemizedlist>]]></programlisting>
	</answer>
	</qandaentry>
	<qandaentry>
	<question>
	<para>When to use <command>, <code>, <programlisting>,
	<screen></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 <command> to mention a command such as <command>hbase
	shell</command> in the flow of a sentence. Use <code> for other
	inline text referring to code. Incidentally, use <literal> to specify
	literal strings that should be typed or entered exactly as shown. Within a
	<screen> listing, it can be helpful to use the <userinput> and
	<computeroutput> elements to mark up the text further.</para>
	<para>Use <screen> to display input and output as the user would
	<emphasis>see</emphasis> it on the screen, in a log file, etc. Use
	<programlisting> 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 &lt; and
	&gt; encoded characters. For longer mentions, or blocks of code, enclose
	it with <![CDATA[<![CDATA[]]>]]>, 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 <screen> and <programlisting> 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 the
	beginning of the programlisting output, do not put the CDATA
	element on its own line. For example:</para>
	<programlisting language="bourne"><![CDATA[ <programlisting>
	case $1 in
	--cleanZk\|--cleanHdfs\|--cleanAll)
	matches="yes" ;;
	*) ;;
	esac
	</programlisting>]]></programlisting>
	</listitem>
	<listitem>
	<para>After pasting code into a programlisting, fix the indentation
	manually, using two <emphasis>spaces</emphasis> per desired
	indentation. For screen output, be sure to include line breaks so
	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>
	<qandaentry>
	<question>
	<para>Syntax Highlighting</para>
	</question>
	<answer>
	<para>The HBase Reference Guide uses the <link
	xlink:href="http://sourceforge.net/projects/xslthl/files/xslthl/2.1.0/"
	>XSLT Syntax Highlighting</link> Maven module for syntax highlighting.
	To enable syntax highlighting for a given <programlisting> or
	<screen> (or possibly other elements), add the attribute
	<literal>language=<replaceable>LANGUAGE_OF_CHOICE</replaceable></literal>
	to the element, as in the following example:</para>
	<programlisting language="xml"><![CDATA[
	<programlisting language="xml">
	<foo>bar</foo>
	<bar>foo</bar>
	</programlisting>]]></programlisting>
	<para>Several syntax types are supported. The most interesting ones for the
	HBase Reference Guide are <literal>java</literal>, <literal>xml</literal>,
	<literal>sql</literal>, and <literal>bourne</literal> (for BASH shell
	output or Linux command-line examples).</para>
	</answer>
	</qandaentry>
	</qandaset>
	</section>
	</appendix>