Apache
/
hbase
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

This commit is contained in:
stack 2014-07-31 19:53:58 -07:00
parent 1326d329ee
commit 33e1418105
3 changed files with 428 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

403
src/main/docbkx/appendix_contributing_to_documentation.xml Normal file
View File

@ -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, 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>$ 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>$ 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, make
sure you rebase your branch against the remote master and take care of any
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, 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><![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><![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><![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><![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>
</qandaset>
</section>
</appendix>

1
src/main/docbkx/book.xml
View File

@ -4442,6 +4442,7 @@ 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>

30
src/main/docbkx/preface.xml
View File

@ -39,14 +39,28 @@
xlink:href="http://wiki.apache.org/hadoop/Hbase">wiki</link> where the pertinent
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 are
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> 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 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 a
volunteer effort, and may be delayed.</para>
</formalpara>
<note
xml:id="headsup">