HBASE-11539 Expand info about contributing to and building documentation (Misty Stanley-Jones)
This commit is contained in:
parent
1326d329ee
commit
33e1418105
|
@ -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 <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><![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><![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><![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><![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>
|
||||
|
||||
|
|
@ -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'>
|
||||
|
|
|
@ -39,15 +39,29 @@
|
|||
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&issuetype=1&components=12312132&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">
|
||||
<title>Heads-up if this is your first foray into the world of distributed
|
||||
|
|
Loading…
Reference in New Issue