src/main/asciidoc/_chapters/preface.adoc

   1 ////
   2 /**
   3  *
   4  * Licensed to the Apache Software Foundation (ASF) under one
   5  * or more contributor license agreements.  See the NOTICE file
   6  * distributed with this work for additional information
   7  * regarding copyright ownership.  The ASF licenses this file
   8  * to you under the Apache License, Version 2.0 (the
   9  * "License"); you may not use this file except in compliance
  10  * with the License.  You may obtain a copy of the License at
  11  *
  12  *     http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  */
  20 ////
  21
  22 [preface]
  23 = Preface
  24 :doctype: article
  25 :numbered:
  26 :toc: left
  27 :icons: font
  28 :experimental:
  29
  30 This is the official reference guide for the link:https://hbase.apache.org/[HBase] version it ships with.
  31
  32 Herein you will find either the definitive documentation on an HBase topic as of its
  33 standing when the referenced HBase version shipped, or it will point to the location
  34 in link:https://hbase.apache.org/apidocs/index.html[Javadoc] or
  35 link:https://issues.apache.org/jira/browse/HBASE[JIRA] where the pertinent information can be found.
  36
  37 .About This Guide
  38 This reference guide is a work in progress. The source for this guide can be found in the
  39 _src/main/asciidoc directory of the HBase source. This reference guide is marked up
  40 using link:http://asciidoc.org/[AsciiDoc] from which the finished guide is generated as part of the
  41 'site' build target. Run
  42 [source,bourne]
  43 ----
  44 mvn site
  45 ----
  46 to generate this documentation.
  47 Amendments and improvements to the documentation are welcomed.
  48 Click
  49 link:https://issues.apache.org/jira/secure/CreateIssueDetails!init.jspa?pid=12310753&issuetype=1&components=12312132&summary=SHORT+DESCRIPTION[this link]
  50 to file a new documentation bug against Apache HBase with some values pre-selected.
  51
  52 .Contributing to the Documentation
  53 For an overview of AsciiDoc and suggestions to get started contributing to the documentation,
  54 see the <<appendix_contributing_to_documentation,relevant section later in this documentation>>.
  55
  56 .Heads-up if this is your first foray into the world of distributed computing...
  57 If this is your first foray into the wonderful world of Distributed Computing, then you are in for some interesting times.
  58 First off, distributed systems are hard; making a distributed system hum requires a disparate skillset that spans systems (hardware and software) and networking.
  59
  60 Your cluster's operation can hiccup because of any of a myriad set of reasons from bugs in HBase itself through misconfigurations -- misconfiguration of HBase but also operating system misconfigurations -- through to hardware problems whether it be a bug in your network card drivers or an underprovisioned RAM bus (to mention two recent examples of hardware issues that manifested as "HBase is slow"). You will also need to do a recalibration if up to this your computing has been bound to a single box.
  61 Here is one good starting point: link:http://en.wikipedia.org/wiki/Fallacies_of_Distributed_Computing[Fallacies of Distributed Computing].
  62
  63 That said, you are welcome. +
  64 It's a fun place to be. +
  65 Yours, the HBase Community.
  66
  67 .Reporting Bugs
  68
  69 Please use link:https://issues.apache.org/jira/browse/hbase[JIRA] to report non-security-related bugs.
  70
  71 To protect existing HBase installations from new vulnerabilities, please *do not* use JIRA to report security-related bugs. Instead, send your report to the mailing list private@hbase.apache.org, which allows anyone to send messages, but restricts who can read them. Someone on that list will contact you to follow up on your report.
  72
  73 [[hbase_supported_tested_definitions]]
  74 .Support and Testing Expectations
  75
  76 The phrases /supported/, /not supported/, /tested/, and /not tested/ occur several
  77 places throughout this guide. In the interest of clarity, here is a brief explanation
  78 of what is generally meant by these phrases, in the context of HBase.
  79
  80 NOTE: Commercial technical support for Apache HBase is provided by many Hadoop vendors.
  81 This is not the sense in which the term /support/ is used in the context of the
  82 Apache HBase project. The Apache HBase team assumes no responsibility for your
  83 HBase clusters, your configuration, or your data.
  84
  85 Supported::
  86   In the context of Apache HBase, /supported/ means that HBase is designed to work
  87   in the way described, and deviation from the defined behavior or functionality should
  88   be reported as a bug.
  89
  90 Not Supported::
  91   In the context of Apache HBase, /not supported/ means that a use case or use pattern
  92   is not expected to work and should be considered an antipattern. If you think this
  93   designation should be reconsidered for a given feature or use pattern, file a JIRA
  94   or start a discussion on one of the mailing lists.
  95
  96 Tested::
  97   In the context of Apache HBase, /tested/ means that a feature is covered by unit
  98   or integration tests, and has been proven to work as expected.
  99
 100 Not Tested::
 101   In the context of Apache HBase, /not tested/ means that a feature or use pattern
 102   may or may not work in a given way, and may or may not corrupt your data or cause
 103   operational issues. It is an unknown, and there are no guarantees. If you can provide
 104   proof that a feature designated as /not tested/ does work in a given way, please
 105   submit the tests and/or the metrics so that other users can gain certainty about
 106   such features or use patterns.
 107
 108 :numbered: