[GitHub] keith-turner closed pull request #109: Document public API

[GitBox <gi...@apache.org>]

keith-turner closed pull request #109: Document public API
URL: https://github.com/apache/accumulo-website/pull/109
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/README.md b/README.md
index e2cd4ce9..11f139d3 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ The source for these tags is at [_plugins/links.rb](_plugins/links.rb).
 
 | Tag   | Description            | Options                                                                         | Examples                                             | 
 | ----- | ---------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| jlink | Creates Javadoc link   | Link text will be class name by default. Use `-f` for full package + class name | `{% jlink -f org.apache.accumulo.core.client.Connector %}` |
+| jlink | Creates Javadoc link   | Link text will be class name by default. Use `-f` for full package + class name | `{% jlink -f org.apache.accumulo.core.client.Connector %}`  `{% jlink -f org.apache.accumulo.core.client %}` |
 | jurl  | Creates Javadoc URL    | None                                                                            | `{% jurl org.apache.accumulo.core.client.Connector %}`     |
 | plink | Creates Property link  | Assumes server property by default. Use `-c` to link to client properties. Accepts server property prefixes (i.e `table.*`)       | `{% plink -c instance.name %}`                             |
 | purl  | Creates Property URL   | Default is server property. Use `-c` to link to client properties. Accepts server property prefixes (i.e `table.*`)               | `{% purl instance.volumes %}`                             |
diff --git a/_docs-2-0/getting-started/clients.md b/_docs-2-0/getting-started/clients.md
index 3cab9e6c..0811c712 100644
--- a/_docs-2-0/getting-started/clients.md
+++ b/_docs-2-0/getting-started/clients.md
@@ -16,6 +16,10 @@ If you are using Maven to create Accumulo client code, add the following to your
 </dependency>
 ```
 
+When writing code that uses Accumulo, only use the [Accumulo Public API](/api).
+The `accumulo-core` artifact includes implementation code that falls outside the
+Public API and should be avoided.
+
 ## Connecting
 
 Before writing Accumulo client code, you will need the following information.
diff --git a/pages/api.md b/pages/api.md
new file mode 100644
index 00000000..66a20852
--- /dev/null
+++ b/pages/api.md
@@ -0,0 +1,35 @@
+---
+title: Public API Definition
+permalink: /api/
+---
+
+Accumulo's public API is composed of all public types in the following
+packages and their sub-packages excluding those named *impl*, *thrift*, or
+*crypto*.
+
+ * {% jlink -f org.apache.accumulo.core.client %}
+ * {% jlink -f org.apache.accumulo.core.data %}
+ * {% jlink -f org.apache.accumulo.core.security %}
+ * {% jlink -f org.apache.accumulo.minicluster %}
+
+A type is a class, interface, or enum. Anything with public or protected
+access in an API type is in the API. This includes, but is not limited to:
+methods, members classes, interfaces, and enums. Package-private types in the
+above packages are *not* considered public API.
+
+The Accumulo project maintains binary compatibility across this API within a
+major release, as defined in the Java Language Specification 3rd ed. Starting
+with Accumulo 1.6.2 and 1.7.0 all API changes follow [semver 2.0][semver].
+Accumulo code outside of the defined API does not follow semver and may change
+in incompatible ways at any release.
+
+The following regex matches imports that are *not* Accumulo public API. This
+regex can be used with [RegexpSingleline] to automatically find suspicious
+imports in a project using Accumulo.
+
+```
+import\s+org\.apache\.accumulo\.(.*\.(impl|thrift|crypto)\..*|(?!core|minicluster).*|core\.(?!client|data|security).*)
+```
+
+[semver]: http://semver.org/spec/v2.0.0
+[RegexpSingleline]: http://checkstyle.sourceforge.net/config_regexp.html
diff --git a/tour/index.md b/tour/index.md
index 9f01ab05..eacba6ae 100644
--- a/tour/index.md
+++ b/tour/index.md
@@ -9,7 +9,7 @@ skiph1fortitle: true
 {% assign first_url = tour_pages[0] | prepend: '/tour/' | append: '/' %}
 {% assign first_page = site.pages | where:'url',first_url | first %}
 
-Welcome to the Accumulo tour! The tour offers a hands on introduction to the Accumulo Java API, broken down into
+Welcome to the Accumulo tour! The tour offers a hands on introduction to the [Accumulo Java API](/api), broken down into
 independent steps and exercises. The exercises give you a chance to apply what you have learned by writing code on your
 own. The answers to an exercise are typically provided in the next step.  The tour starts with a 
 [{{ first_page.title }}]({{ first_url }}) page that will help you get set up.


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services