You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zookeeper.apache.org by an...@apache.org on 2018/10/15 14:47:26 UTC
[3/3] zookeeper git commit: ZOOKEEPER-3154: Update release process to
use the MarkDown solution
ZOOKEEPER-3154: Update release process to use the MarkDown solution
Added `mvn clean` and `mvn install` to `ant clean` and `ant compile` as dependency.
This way we clean and build zookeeper-docs maven sub-project when we clean and build main ant project.
Added releasenotes.md and fixed small issues in MarkDown files.
Next step is to remove not needed forrest content and dead ant code.
Only valid for branch-3.4.
Change-Id: I308a970c253be1bb82387516bf7b08bd7818a2c7
Author: Tamas Penzes <ta...@cloudera.com>
Reviewers: andor@apache.org
Closes #664 from tamaashu/ZOOKEEPER-3154-3.4 and squashes the following commits:
16a078e1 [Tamas Penzes] ZOOKEEPER-3154: Removed HTML document generation which will be put back when maven migration will be done
be39d02f [Tamas Penzes] ZOOKEEPER-3154: Update release process to use the MarkDown solution
Project: http://git-wip-us.apache.org/repos/asf/zookeeper/repo
Commit: http://git-wip-us.apache.org/repos/asf/zookeeper/commit/f0c86834
Tree: http://git-wip-us.apache.org/repos/asf/zookeeper/tree/f0c86834
Diff: http://git-wip-us.apache.org/repos/asf/zookeeper/diff/f0c86834
Branch: refs/heads/branch-3.4
Commit: f0c868346a308a60927dca0c1c1fd6382651dbd1
Parents: c0aa3b3
Author: Tamas Penzes <ta...@cloudera.com>
Authored: Mon Oct 15 16:47:20 2018 +0200
Committer: Andor Molnar <an...@apache.org>
Committed: Mon Oct 15 16:47:20 2018 +0200
----------------------------------------------------------------------
build.xml | 12 +-
.../main/resources/markdown/bookkeeperConfig.md | 12 +-
.../resources/markdown/bookkeeperOverview.md | 18 +-
.../resources/markdown/bookkeeperProgrammer.md | 18 +-
.../resources/markdown/bookkeeperStarted.md | 16 +-
.../main/resources/markdown/bookkeeperStream.md | 8 +-
.../src/main/resources/markdown/index.md | 2 +-
.../src/main/resources/markdown/javaExample.md | 2 +-
.../src/main/resources/markdown/recipes.md | 4 +-
.../src/main/resources/markdown/releasenotes.md | 813 +++++++++++++++++++
.../main/resources/markdown/zookeeperAdmin.md | 6 +-
.../main/resources/markdown/zookeeperOver.md | 2 +-
.../resources/markdown/zookeeperProgrammers.md | 10 +-
.../main/resources/markdown/zookeeperStarted.md | 4 +-
14 files changed, 872 insertions(+), 55 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/f0c86834/build.xml
----------------------------------------------------------------------
diff --git a/build.xml b/build.xml
index 9cce946..6a1ef2b 100644
--- a/build.xml
+++ b/build.xml
@@ -859,8 +859,10 @@ xmlns:cs="antlib:com.puppycrawl.tools.checkstyle">
</copy>
<copy todir="${dist.dir}/docs">
- <fileset dir="${docs.dir}" />
- <fileset dir="${build.docs}"/>
+ <fileset dir="zookeeper-docs/src/main/resources/markdown/" includes="**">
+ <exclude name="html/**" />
+ </fileset>
+ <fileset dir="${build.docs}"/>
</copy>
<copy todir="${dist.dir}">
@@ -986,8 +988,10 @@ xmlns:cs="antlib:com.puppycrawl.tools.checkstyle">
</copy>
<copy todir="${dist.dir}/docs">
- <fileset dir="${docs.dir}" />
- <fileset dir="${build.docs}"/>
+ <fileset dir="zookeeper-docs/src/main/resources/markdown/" includes="**">
+ <exclude name="html/**" />
+ </fileset>
+ <fileset dir="${build.docs}" />
</copy>
<copy todir="${dist.dir}">
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/f0c86834/zookeeper-docs/src/main/resources/markdown/bookkeeperConfig.md
----------------------------------------------------------------------
diff --git a/zookeeper-docs/src/main/resources/markdown/bookkeeperConfig.md b/zookeeper-docs/src/main/resources/markdown/bookkeeperConfig.md
index f153fa1..304dabb 100644
--- a/zookeeper-docs/src/main/resources/markdown/bookkeeperConfig.md
+++ b/zookeeper-docs/src/main/resources/markdown/bookkeeperConfig.md
@@ -14,8 +14,8 @@ See the License for the specific language governing permissions and
limitations under the License.
//-->
-#BookKeeper Administrator's Guide
-###Setup Guide
+# BookKeeper Administrator's Guide
+### Setup Guide
* [Deployment](#bk_deployment)
* [System requirements](#bk_sysReq)
* [Running bookies](#bk_runningBookies)
@@ -23,7 +23,7 @@ limitations under the License.
<a name="bk_deployment"></a>
-##Deployment
+## Deployment
This section contains information about deploying BookKeeper and
covers these topics:</p>
@@ -37,7 +37,7 @@ respect to ZooKeeper.
<a name="bk_sysReq"></a>
-###System requirements
+### System requirements
A typical BookKeeper installation comprises a set of bookies and a set of ZooKeeper replicas. The exact number of bookies
depends on the quorum mode, desired throughput, and number of clients using this installation simultaneously. The minimum number of
bookies is three for self-verifying (stores a message authentication code along with each entry) and four for generic (does not
@@ -54,7 +54,7 @@ replicas
<a name="bk_runningBookies"></a>
-###Running bookies
+### Running bookies
To run a bookie, we execute the following command:
java -cp .:./zookeeper-<version>-bookkeeper.jar:./zookeeper-<version>.jar\
@@ -73,7 +73,7 @@ Ideally, `/path_to_log_device/` and `/path_to_ledger_device/` are each in a diff
<a name="bk_zkMetadata"></a>
-###ZooKeeper Metadata
+### ZooKeeper Metadata
For BookKeeper, we require a ZooKeeper installation to store metadata, and to pass the list
of ZooKeeper servers as parameter to the constructor of the BookKeeper class (`org.apache.bookkeeper.client,BookKeeper`).
To setup ZooKeeper, please check the [ZooKeeper documentation](index.html)
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/f0c86834/zookeeper-docs/src/main/resources/markdown/bookkeeperOverview.md
----------------------------------------------------------------------
diff --git a/zookeeper-docs/src/main/resources/markdown/bookkeeperOverview.md b/zookeeper-docs/src/main/resources/markdown/bookkeeperOverview.md
index d6f62c9..d8e99a8 100644
--- a/zookeeper-docs/src/main/resources/markdown/bookkeeperOverview.md
+++ b/zookeeper-docs/src/main/resources/markdown/bookkeeperOverview.md
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
limitations under the License.
//-->
-#BookKeeper overview
+# BookKeeper overview
* [BookKeeper overview](#bk_Overview)
* [BookKeeper introduction](#bk_Intro)
@@ -26,10 +26,10 @@ limitations under the License.
<a name="bk_Overview"></a>
-##BookKeeper overview
+## BookKeeper overview
<a name="bk_Intro"></a>
-###BookKeeper introduction
+### BookKeeper introduction
BookKeeper is a replicated service to reliably log streams of records. In BookKeeper,
servers are "bookies", log streams are "ledgers", and each unit of a log (aka record) is a
"ledger entry". BookKeeper is designed to be reliable; bookies, the servers that store
@@ -51,7 +51,7 @@ sets of bookies, and there are a few advantages in having such a service:
<a name="bk_moreDetail"></a>
-###In slightly more detail...
+### In slightly more detail...
BookKeeper implements highly available logs, and it has been designed with write-ahead logging in mind. Besides high availability
due to the replicated nature of the service, it provides high throughput due to striping. As we write entries in a subset of bookies of an
ensemble and rotate writes across available quorums, we are able to increase throughput with the number of servers for both reads and writes.
@@ -72,7 +72,7 @@ for the ledger.
<a name="bk_basicComponents"></a>
-###Bookkeeper elements and concepts
+### Bookkeeper elements and concepts
BookKeeper uses four basic elements:
* **Ledger**: A ledger is a sequence of entries, and each entry is a sequence of bytes. Entries are
@@ -88,7 +88,7 @@ to ledgers and available bookies. We currently use ZooKeeper for such a task.
<a name="bk_initialDesign"></a>
-###Bookkeeper initial design
+### Bookkeeper initial design
A set of bookies implements BookKeeper, and we use a quorum-based protocol to replicate data across the bookies.
There are basically two operations to an existing ledger: read and append. Here is the complete API list
(mode detail [here](bookkeeperProgrammer.html)):
@@ -119,7 +119,7 @@ start a new one for its use.
A client library takes care of communicating with bookies and managing entry numbers. An entry has the following fields:
-#####Entry fields
+##### Entry fields
| Field | Type | Description |
|---------------|------|------------------------------------|
| Ledger number | long | The id of the ledger of this entry |
@@ -151,7 +151,7 @@ as long as enough bookies are up we are guaranteed to eventually be able to read
<a name="bk_metadata"></a>
-###Bookkeeper metadata management
+### Bookkeeper metadata management
There are some meta data that needs to be made available to BookKeeper clients:
* The available bookies;
@@ -165,7 +165,7 @@ were used to store the ledger. Bookies also watch the ledger list so that they c
<a name="bk_closingOut"></a>
-###Closing out ledgers
+### Closing out ledgers
The process of closing out the ledger and finding the last ledger is difficult due to the durability guarantees of BookKeeper:
* If an entry has been successfully recorded, it must be readable.
* If an entry is read once, it must always be available to be read.
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/f0c86834/zookeeper-docs/src/main/resources/markdown/bookkeeperProgrammer.md
----------------------------------------------------------------------
diff --git a/zookeeper-docs/src/main/resources/markdown/bookkeeperProgrammer.md b/zookeeper-docs/src/main/resources/markdown/bookkeeperProgrammer.md
index 0144299..df78b6c 100644
--- a/zookeeper-docs/src/main/resources/markdown/bookkeeperProgrammer.md
+++ b/zookeeper-docs/src/main/resources/markdown/bookkeeperProgrammer.md
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
limitations under the License.
//-->
-#BookKeeper Getting Started Guide
+# BookKeeper Getting Started Guide
* [Programming with BookKeeper](#bk_GettingStarted)
* [Instantiating BookKeeper](#bk_instance)
@@ -27,7 +27,7 @@ limitations under the License.
<a name="bk_GettingStarted"></a>
-##Programming with BookKeeper
+## Programming with BookKeeper
* [Instantiating BookKeeper](#bk_instance)
* [Creating a ledger](#bk_createLedger)
@@ -39,7 +39,7 @@ limitations under the License.
<a name="bk_instance"></a>
-###Instantiating BookKeeper
+### Instantiating BookKeeper
The first step to use BookKeeper is to instantiate a BookKeeper object:
org.apache.bookkeeper.BookKeeper
@@ -74,7 +74,7 @@ the application also using ZooKeeper and wants to have a single instance of ZooK
<a name="bk_createLedger"></a>
-###Creating a ledger
+### Creating a ledger
Before writing entries to BookKeeper, it is necessary to create a ledger.
With the current BookKeeper API, it is possible to create a ledger both synchronously
@@ -129,7 +129,7 @@ is the one same returned in the callback.
<a name="bk_writeLedger"></a>
-###Adding entries to a ledger
+### Adding entries to a ledger
Once we have a ledger handle `lh` obtained through a call to create a ledger, we
can start writing entries. As with creating ledgers, we can write both synchronously and
@@ -168,7 +168,7 @@ where:
<a name="bk_closeLedger"></a>
-###Closing a ledger
+### Closing a ledger
Once a client is done writing, it closes the ledger. The following methods belong
@@ -201,7 +201,7 @@ where:
<a name="bk_openLedger"></a>
-###Opening a ledger
+### Opening a ledger
To read from a ledger, a client must open it first. The following methods belong
to `org.apache.bookkeeper.client.BookKeeper`.
@@ -235,7 +235,7 @@ where:
<a name="bk_readLedger"></a>
-###Reading from ledger
+### Reading from ledger
Read calls may request one or more consecutive entries. The following methods belong
to `org.apache.bookkeeper.client.LedgerHandle`.
@@ -270,7 +270,7 @@ where:
<a name="bk_deleteLedger"></a>
-###Deleting a ledger
+### Deleting a ledger
Once a client is done with a ledger and is sure that nobody will ever need to read from it again, they can delete the ledger.
The following methods belong to `org.apache.bookkeeper.client.BookKeeper`.
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/f0c86834/zookeeper-docs/src/main/resources/markdown/bookkeeperStarted.md
----------------------------------------------------------------------
diff --git a/zookeeper-docs/src/main/resources/markdown/bookkeeperStarted.md b/zookeeper-docs/src/main/resources/markdown/bookkeeperStarted.md
index 1cbb33b..43270cc 100644
--- a/zookeeper-docs/src/main/resources/markdown/bookkeeperStarted.md
+++ b/zookeeper-docs/src/main/resources/markdown/bookkeeperStarted.md
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
limitations under the License.
//-->
-#BookKeeper Getting Started Guide
+# BookKeeper Getting Started Guide
* [Getting Started: Setting up BookKeeper to write logs.](#bk_GettingStarted)
* [Pre-requisites](#bk_Prerequisites)
@@ -26,7 +26,7 @@ limitations under the License.
<a name="bk_GettingStarted"></a>
-##Getting Started: Setting up BookKeeper to write logs.
+## Getting Started: Setting up BookKeeper to write logs.
This document contains information to get you started quickly with
BookKeeper. It is aimed primarily at developers willing to try it out, and
contains simple installation instructions for a simple BookKeeper installation
@@ -35,19 +35,19 @@ and a simple programming example. For further programming detail, please refer t
<a name="bk_Prerequisites"></a>
-###Pre-requisites
+### Pre-requisites
See [System Requirements](bookkeeperConfig.html#bk_sysReq) in the Admin guide.
<a name="bk_Download"></a>
-###Download
+### Download
BookKeeper is distributed along with ZooKeeper. To get a ZooKeeper distribution,
download a recent [stable](http://zookeeper.apache.org/releases.html)
release from one of the Apache Download Mirrors.
<a name="bk_localBK"></a>
-###LocalBookKeeper
+### LocalBookKeeper
Under `org.apache.bookkeeper.util`, you'll find a java program
called LocalBookKeeper.java that sets you up to run BookKeeper on a
single machine. This is far from ideal from a performance perspective,
@@ -55,7 +55,7 @@ but the program is useful for both test and educational purposes.
<a name="bk_setupBookies"></a>
-###Setting up bookies
+### Setting up bookies
If you're bold and you want more than just running things locally, then
you'll need to run bookies in different servers. You'll need at least three bookies
to start with.
@@ -76,7 +76,7 @@ values corresponding to them.
<a name="bk_setupZK"></a>
-###Setting up ZooKeeper
+### Setting up ZooKeeper
ZooKeeper stores metadata on behalf of BookKeeper clients and bookies. To get a minimal
ZooKeeper installation to work with BookKeeper, we can set up one server running in
standalone mode. Once we have the server running, we need to create a few znodes:
@@ -90,7 +90,7 @@ standalone mode. Once we have the server running, we need to create a few znodes
<a name="bk_example"></a>
-###Example
+### Example
In the following excerpt of code, we:
1. Create a ledger;
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/f0c86834/zookeeper-docs/src/main/resources/markdown/bookkeeperStream.md
----------------------------------------------------------------------
diff --git a/zookeeper-docs/src/main/resources/markdown/bookkeeperStream.md b/zookeeper-docs/src/main/resources/markdown/bookkeeperStream.md
index e1e6a38..a86e580 100644
--- a/zookeeper-docs/src/main/resources/markdown/bookkeeperStream.md
+++ b/zookeeper-docs/src/main/resources/markdown/bookkeeperStream.md
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
limitations under the License.
//-->
-#Streaming with BookKeeper
+# Streaming with BookKeeper
* [Summary](#bk_StreamSummary)
* [Writing a stream of bytes](#bk_LedgerOutputStream)
@@ -22,7 +22,7 @@ limitations under the License.
<a name="bk_StreamSummary"></a>
-##Summary
+## Summary
When using the BookKeeper API, an application has to split the data to write into entries, each
entry being a byte array. This is natural for many applications. For example, when using BookKeeper
@@ -36,7 +36,7 @@ The stream API is implemented in the package `Streaming`, and it contains two ma
<a name="bk_LedgerOutputStream"></a>
-##Writing a stream of bytes
+## Writing a stream of bytes
Class `LedgerOutputStream` implements two constructors and five public methods:
@@ -89,7 +89,7 @@ where:
<a name="bk_LedgerInputStream"></a>
-##Reading a stream of bytes
+## Reading a stream of bytes
Class `LedgerOutputStream` implements two constructors and four public methods:
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/f0c86834/zookeeper-docs/src/main/resources/markdown/index.md
----------------------------------------------------------------------
diff --git a/zookeeper-docs/src/main/resources/markdown/index.md b/zookeeper-docs/src/main/resources/markdown/index.md
index 9048171..f96568c 100644
--- a/zookeeper-docs/src/main/resources/markdown/index.md
+++ b/zookeeper-docs/src/main/resources/markdown/index.md
@@ -36,7 +36,7 @@ archives.
+ [Release Notes](releasenotes.html) - new developer and user facing features, improvements, and incompatibilities
+ **Developers**
Documents for Developers using the ZooKeeper Client API
- + [API Docs](index.html) - the technical reference to ZooKeeper Client APIs
+ + [API Docs](api/index.html) - the technical reference to ZooKeeper Client APIs
+ [Programmer's Guide](zookeeperProgrammers.html) - a client application developer's guide to ZooKeeper
+ [ZooKeeper Java Example](javaExample.html) - a simple Zookeeper client appplication, written in Java
+ [Barrier and Queue Tutorial](zookeeperTutorial.html) - sample implementations of barriers and queues
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/f0c86834/zookeeper-docs/src/main/resources/markdown/javaExample.md
----------------------------------------------------------------------
diff --git a/zookeeper-docs/src/main/resources/markdown/javaExample.md b/zookeeper-docs/src/main/resources/markdown/javaExample.md
index b33963c..536b520 100644
--- a/zookeeper-docs/src/main/resources/markdown/javaExample.md
+++ b/zookeeper-docs/src/main/resources/markdown/javaExample.md
@@ -237,7 +237,7 @@ sets a watch, and passes a reference to itself (`this`)
as the completion callback object. In this sense, it kicks things off, since the
real processing happens when the watch is triggered.
-######Note
+###### Note
>Don't confuse the completion callback with the watch callback. The `ZooKeeper.exists()`
completion callback, which happens to be the method `StatCallback.processResult()` implemented
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/f0c86834/zookeeper-docs/src/main/resources/markdown/recipes.md
----------------------------------------------------------------------
diff --git a/zookeeper-docs/src/main/resources/markdown/recipes.md b/zookeeper-docs/src/main/resources/markdown/recipes.md
index 7d160e2..8ae82cf 100644
--- a/zookeeper-docs/src/main/resources/markdown/recipes.md
+++ b/zookeeper-docs/src/main/resources/markdown/recipes.md
@@ -167,7 +167,7 @@ the list obtained from the first **getChildren(
)** call. If there are are no children in the queue node, the
reader waits for a watch notification to check the queue again.
-######Note
+###### Note
>There now exists a Queue implementation in ZooKeeper
recipes directory. This is distributed with the release --
zookeeper-recipes/zookeeper-recipes-queue directory of the release artifact.
@@ -194,7 +194,7 @@ any snapshot in time no two clients think they hold the same lock. These
can be implemented using ZooKeeeper. As with priority queues, first define
a lock node.
-######Note
+###### Note
>There now exists a Lock implementation in ZooKeeper
recipes directory. This is distributed with the release --
zookeeper-recipes/zookeeper-recipes-lock directory of the release artifact.