diff --git src/main/docbkx/appendix_contributing_to_documentation.xml src/main/docbkx/appendix_contributing_to_documentation.xml new file mode 100644 index 0000000..080525a --- /dev/null +++ src/main/docbkx/appendix_contributing_to_documentation.xml @@ -0,0 +1,403 @@ + + + + + Contributing to Documentation + 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: + + + The HBase Reference + Guide (this book) + + + The HBase websitee + + + The HBase + Wiki + + + API documentation + + + Command-line utility output and help text + + + Web UI strings, explicit help text, context-sensitive strings, and others + + + Log messages + + + Comments in source files, configuration files, and others + + + Localization of any of the above into target languages other than English + + + 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 . + +
+ Getting Access to the Wiki + 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 https://wiki.apache.org/hadoop/Hbase?action=newaccount. Contact one of the + HBase committers, who can either give you access or refer you to someone who can. +
+
+ Contributing to Documentation or Other Strings + 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 Documentation 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. + 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. + + Suggested Work flow for Submitting Patches + 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. + + If you have not already done so, clone the Git repository locally. You only + need to do this once. + + + Fairly often, pull remote changes into your local repository by using the + git pull command, while your master branch is checked + out. + + + 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: + $ git checkout -b HBASE-123456 + + + 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. + + + 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. + + Before you use the site target the very first time, be + sure you have built HBase at least once, in order to fetch all the Maven + dependencies you need. + + $ mvn clean install -DskipTests # Builds HBase + $ mvn clean site -DskipTests # Builds the website and documentation + If any errors occur, address them. + + + 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. + +$ git checkout HBASE-123456 +$ git rebase origin/master + + + + Generate your patch against the remote master. Run the following command from + the top level of your git repository (usually called + hbase): + $ git diff --no-prefix origin/master > HBASE-123456.patch + 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 Patch Available 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. + + + After a change has been committed, there is no need to keep your local branch + around. Instead you should run git pull to get the new change + into your master branch. + + +
+ +
+ Editing the HBase Website + The source for the HBase website is in the HBase source, in the + src/main/site/ directory. Within this directory, source for the + individual pages is in the xdocs/ directory, and images referenced + in those pages are in the images/ directory. This directory also + stores images used in the HBase Reference Guide. + The website's pages are written in an HTML-like XML dialect called xdoc, which has a + reference guide at http://maven.apache.org/archives/maven-1.x/plugins/xdoc/reference/xdocs.html. + 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. + To preview your changes, build the website using the mvn clean site + -DskipTests command. The HTML output resides in the + target/site/ directory. When you are satisfied with your + changes, follow the procedure in to submit + your patch. +
+ +
+ Editing the HBase Reference Guide + The source for the HBase Reference Guide is in the HBase source, in the + src/main/docbkx/ directory. It is written in Docbook 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. + Docbook's syntax can be picky. Before submitting a patch, be sure to build the output + locally using the mvn site 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 target/docbkx/ for any surprises before submitting a + patch. +
+ +
+ Auto-Generated Content + Some parts of the HBase Reference Guide, most notably , + 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 src/main/xslt/configuration_to_docbook_section.xsl. This + transforms the hbase-common/src/main/resources/hbase-default.xml + 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. + It is possible that other types of content can and will be automatically generated + from HBase source files in the future. +
+ +
+ Multi-Page and Single-Page Output + You can examine the site target in the Maven + pom.xml 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 target/docbkx/book.html, while the + multi-page output's index page is at target/docbkx/book/book.html. + Each of these outputs has its own images/ and + css/ directories, which are created at build time. +
+ +
+ Images in the HBase Reference Guide + 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. + + HFile Version 1 + + + + + + HFile Version 1 + + +]]> + + 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. + When doing a local build, save the image to the + src/main/site/resources/images/ 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. + 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. +
+ +
+ Adding a New Chapter to the HBase Reference Guide + 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 + book.xml 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 book.xml 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. +
+ +
+ Docbook Common Issues + The following Docbook issues come up often. Some of these are preferences, but others + can create mysterious build errors or other problems. + + + + What can go where? + + + There is often confusion about which child elements are valid in a given + context. When in doubt, Docbook: The + Definitive Guide 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. + + + + + Paragraphs and Admonitions + + + 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: + This is the paragraph. + + This is an admonition which occurs after the paragraph. +]]> + + + + + Wrap textual <listitem> and <entry> contents in <para> + elements. + + + 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. + + + This is a paragraph. + + + This is screen output. + +]]> + + + + + When to use <command>, <code>, <programlisting>, + <screen> + + + The first two are in-line tags, which can occur within the flow of + paragraphs or titles. The second two are block elements. + Use <command> to mention a command such as hbase + shell 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. + Use <screen> to display input and output as the user would + see 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. + + + + + How to escape XML elements so that they show up as XML + + + 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 , which is much easier to maintain and + parse in the source files.. + + + + + Tips and tricks for making screen output look good + + + Text within <screen> and <programlisting> elements is shown + exactly as it appears in the source, including indentation, tabs, and line + wrap. + + + 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: + +case $1 in + --cleanZk|--cleanHdfs|--cleanAll) + matches="yes" ;; + *) ;; +esac + ]]> + + + After pasting code into a programlisting, fix the indentation + manually, using two spaces per desired + indentation. For screen output, be sure to include line breaks so + that the text is no longer than 100 characters. + + + + + + + Isolate Changes for Easy Diff Review. + + + 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. + + + +
+
+ + \ No newline at end of file diff --git src/main/docbkx/book.xml src/main/docbkx/book.xml index 2a2e994..0564354 100644 --- src/main/docbkx/book.xml +++ src/main/docbkx/book.xml @@ -4442,7 +4442,8 @@ if (result.isStale()) { - + + FAQ diff --git src/main/docbkx/preface.xml src/main/docbkx/preface.xml index ff8efb9..5885bfe 100644 --- src/main/docbkx/preface.xml +++ src/main/docbkx/preface.xml @@ -39,15 +39,29 @@ xlink:href="http://wiki.apache.org/hadoop/Hbase">wiki where the pertinent information can be found. - This reference guide is a work in progress. The source for this guide can be found at - src/main/docbkx in a checkout of the hbase project. This reference - guide is marked up using DocBook from which the the finished guide is - generated as part of the 'site' build target. Run mvn site - to generate this documentation. Amendments and improvements to the documentation are - welcomed. Add a patch to an issue up in the HBase JIRA. - + + About This Guide + This reference guide is a work in progress. The source for this guide can be found in + the src/main/docbkx directory of the HBase source. This reference + guide is marked up using DocBook from + which the the finished guide is generated as part of the 'site' build target. Run + mvn site to generate this documentation. Amendments and + improvements to the documentation are welcomed. Click this link to file a new documentation bug against Apache HBase with some + values pre-selected. + + + Contributing to the Documentation + For an overview of Docbook and suggestions to get started contributing to the documentation, see . + + + Providing Feedback + 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. + + Heads-up if this is your first foray into the world of distributed