bookkeeper-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From si...@apache.org
Subject [bookkeeper] branch master updated: ISSUE #325: [WEBSITE] how to manage documentation between releases
Date Mon, 07 Aug 2017 18:25:11 GMT
This is an automated email from the ASF dual-hosted git repository.

sijie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/bookkeeper.git


The following commit(s) were added to refs/heads/master by this push:
     new ae1ba84  ISSUE #325: [WEBSITE] how to manage documentation between releases
ae1ba84 is described below

commit ae1ba84f0935fdac43e7dd500647a70b2c4ca7f3
Author: Sijie Guo <sijie@apache.org>
AuthorDate: Mon Aug 7 11:25:02 2017 -0700

    ISSUE #325: [WEBSITE] how to manage documentation between releases
    
    Descriptions of the changes in this PR:
    
    - move `docs` to `docs/latest`
    - add a script to proceed release steps
       - copy `docs/latest` to `docs/{version}`
       - in docs/{version}, replace versions
       - bump versions in `_config.yml`
       - generate placeholders for releaseNotes
    
    Author: Sijie Guo <sijie@apache.org>
    
    Reviewers: Luc Perkins <lucperkins@gmail.com>, Jia Zhai <None>
    
    This closes #400 from sijie/release_versions, closes #325
---
 site/_config.yml                                   |  8 +-
 site/_data/releaseNotesSummary.template            |  4 +
 site/_includes/download-button.html                |  4 +-
 site/_includes/javadoc-button.html                 |  2 +-
 site/_includes/navbar.html                         | 17 +++--
 site/_includes/sidebar.html                        | 15 ++--
 site/docs/{ => latest}/admin/autorecovery.md       |  8 +-
 site/docs/{ => latest}/admin/bookies.md            |  0
 site/docs/{ => latest}/admin/geo-replication.md    |  0
 site/docs/{ => latest}/admin/metrics.md            |  0
 site/docs/{ => latest}/admin/perf.md               |  0
 site/docs/{ => latest}/admin/placement.md          |  0
 site/docs/{ => latest}/api/distributedlog-api.md   | 10 +--
 site/docs/{ => latest}/api/ledger-api.md           | 12 +--
 site/docs/{ => latest}/api/overview.md             |  0
 site/docs/{ => latest}/deployment/dcos.md          | 10 +--
 site/docs/{ => latest}/deployment/kubernetes.md    |  0
 site/docs/{ => latest}/deployment/manual.md        |  0
 site/docs/{ => latest}/development/codebase.md     |  0
 site/docs/{ => latest}/development/protocol.md     |  0
 site/docs/{ => latest}/example.md                  |  0
 site/docs/{ => latest}/getting-started/concepts.md | 11 ++-
 .../{ => latest}/getting-started/installation.md   |  8 +-
 .../{ => latest}/getting-started/run-locally.md    |  4 +-
 site/docs/latest/index.md                          | 57 ++++++++++++++
 site/docs/{ => latest}/reference/cli.md            |  0
 site/docs/{ => latest}/reference/config.md         |  0
 site/docs/{ => latest}/reference/metrics.md        |  0
 site/docs/latest/releaseNotes.md                   | 13 ++++
 site/docs/latest/releaseNotesTemplate.md           | 18 +++++
 site/index.html                                    |  4 +-
 site/releases.md                                   | 30 ++++----
 site/scripts/common.sh                             |  3 +-
 site/scripts/release.sh                            | 88 ++++++++++++++++++++++
 34 files changed, 255 insertions(+), 71 deletions(-)

diff --git a/site/_config.yml b/site/_config.yml
index 4f9e76c..e9ac329 100644
--- a/site/_config.yml
+++ b/site/_config.yml
@@ -1,9 +1,8 @@
 title: Apache BookKeeper
-subtitle: A replicated log service
+subtitle: A scalable, fault-tolerant, and low-latency storage serivce optimized for real-time
workloads
 github_repo: https://github.com/apache/bookkeeper
 github_master: https://github.com/apache/bookkeeper/tree/master
 permalink: pretty
-bk_version: "4.5.0"
 baseurl: /
 destination: local-generated
 twitter_url: https://twitter.com/asfbookkeeper
@@ -11,7 +10,8 @@ twitter_url: https://twitter.com/asfbookkeeper
 livereload: true
 
 versions:
-- "4.5.0"
+# [next_version_placehodler]
+
 archived_versions:
 - "4.4.0"
 - "4.3.2"
@@ -24,7 +24,7 @@ archived_versions:
 - "4.2.0"
 - "4.1.0"
 - "4.0.0"
-latest: "4.5.0"
+latest_version: "4.5.0-SNAPSHOT"
 latest_release: "4.4.0"
 stable_release: "4.4.0"
 distributedlog_version: "2.1.0-0.4.0"
diff --git a/site/_data/releaseNotesSummary.template b/site/_data/releaseNotesSummary.template
new file mode 100644
index 0000000..0468704
--- /dev/null
+++ b/site/_data/releaseNotesSummary.template
@@ -0,0 +1,4 @@
+
+### [date] Release {{ site.latest_version }} available
+
+[INSERT SUMMARY]
diff --git a/site/_includes/download-button.html b/site/_includes/download-button.html
index 8bba114..4fd0753 100644
--- a/site/_includes/download-button.html
+++ b/site/_includes/download-button.html
@@ -1,6 +1,6 @@
-<a class="button is-primary" href="{{ site.baseurl }}docs/getting-started" download>
+<a class="button is-primary" href="{{ site.baseurl }}docs/latest/getting-started" download>
   <span class="icon">
     <i class="fa fa-download"></i>
   </span>
-  <span>Download BookKeeper {{ site.bk_version }}</span>
+  <span>Download BookKeeper {{ site.latest_version }}</span>
 </a>
diff --git a/site/_includes/javadoc-button.html b/site/_includes/javadoc-button.html
index 017144e..31d3738 100644
--- a/site/_includes/javadoc-button.html
+++ b/site/_includes/javadoc-button.html
@@ -1,4 +1,4 @@
-<a class="button is-large" href="{{ site.baseurl }}javadoc">
+<a class="button is-large" href="{{ site.baseurl }}docs/latest/api/javadoc">
   <span class="icon">
     <img src="{{ site.baseurl }}img/java-icon.svg">
   </span>
diff --git a/site/_includes/navbar.html b/site/_includes/navbar.html
index 72b5e33..329dbc4 100644
--- a/site/_includes/navbar.html
+++ b/site/_includes/navbar.html
@@ -31,20 +31,23 @@
       <div class="navbar-item has-dropdown is-hoverable">
         <a class="navbar-link">Documentation</a>
         <div class="navbar-dropdown is-boxed">
-          {% for version in site.versions %}
-          <a class="navbar-item" href="{{ site.baseurl }}docs/getting-started/installation">
-            Release {{version}}
-            {% if version == site.latest %}<span class="tag is-success">LATEST</span>{%
endif %}
+          <a class="navbar-item" href="{{ site.baseurl }}docs/latest/index.html">
+            Version {{ site.latest_version}}
+            <span class="tag is-warning">Development</span>
           </a>
-          {% endfor %}
-          <hr class="dropdown-divider">
-          <a class="navbar-item" href="{{ site.baseurl }}javadoc">
+          <a class="navbar-item" href="{{ site.baseurl }}docs/latest/api/javadoc">
             <span class="icon bk-javadoc-icon">
               <img src="{{ site.baseurl }}img/java-icon.svg">
             </span>
             Javadoc
           </a>
           <hr class="dropdown-divider">
+          {% for version in site.versions %}
+          <a class="navbar-item" href="{{ site.baseurl }}docs/{{version}}/index.html">
+            Release {{version}}
+            {% if version == site.stable_release %}<span class="tag is-success">Stable</span>{%
endif %}
+          </a>
+          {% endfor %}
           {% for version in site.archived_versions %}
           <a class="navbar-item" href="{{ site.baseurl }}archives/docs/r{{version}}">
             Release {{version}}
diff --git a/site/_includes/sidebar.html b/site/_includes/sidebar.html
index c949194..685a9b3 100644
--- a/site/_includes/sidebar.html
+++ b/site/_includes/sidebar.html
@@ -1,23 +1,24 @@
 {% unless page.no_sidebar %}
 <aside class="sidebar">
+  {% assign doc_version = page.url | replace:'/',' ' | truncatewords: 2 | remove:'...' |
replace:'docs','' | lstrip %}
+  <a class="button is-info">
+    Version : {{ doc_version }}
+  </a>
+  <hr />
   {% for group in site.data.sidebar.groups %}{% assign docs = group.docs %}
   <p>
     {{ group.name }}
   </p>
   <ul class="sidebar-items">
     {% for doc in docs %}
-    {% capture doc_url %}{{ site.baseurl }}docs/{{ group.dir }}/{{ doc.endpoint }}/{% endcapture
%}
+    {% capture doc_url %}{{ site.baseurl }}docs/{{ doc_version }}/{{ group.dir }}/{{ doc.endpoint
}}/{% endcapture %}
     <li{% if doc_url == page.url %} class="active"{% endif %}>
-      <a href="{{ site.baseurl }}docs/{{ group.dir }}/{{ doc.endpoint }}">
+      <a href="{{ site.baseurl }}docs/{{ doc_version }}/{{ group.dir }}/{{ doc.endpoint
}}">
       {{ doc.name }}
       </a>
     </li>
     {% endfor %}
   </ul>
   {% endfor %}
-  <hr />
-  <a class="button is-info">
-    Latest version: {{ site.latest }}
-  </a>
 </aside>
-{% endunless %}
\ No newline at end of file
+{% endunless %}
diff --git a/site/docs/admin/autorecovery.md b/site/docs/latest/admin/autorecovery.md
similarity index 90%
rename from site/docs/admin/autorecovery.md
rename to site/docs/latest/admin/autorecovery.md
index e3f5746..64c6beb 100644
--- a/site/docs/admin/autorecovery.md
+++ b/site/docs/latest/admin/autorecovery.md
@@ -91,10 +91,10 @@ $ bookkeeper-server/bin/bookkeeper shell autorecovery -enable
 
 AutoRecovery has two components:
 
-1. The [**auditor**](#auditor) (see the [`Auditor`]({{ site.baseurl }}javadoc/org/apache/bookkeeper/replication/Auditor.html)
class) is a singleton node that watches bookies to see if they fail and creates rereplication
tasks for the ledgers on failed bookies.
-1. The [**replication worker**](#replication-worker) (see the [`ReplicationWorker`]({{ site.baseurl
}}javadoc/org/apache/bookkeeper/replication/ReplicationWorker.html) class) runs on each bookie
and executes rereplication tasks provided by the auditor.
+1. The [**auditor**](#auditor) (see the [`Auditor`](../../api/javadoc/org/apache/bookkeeper/replication/Auditor.html)
class) is a singleton node that watches bookies to see if they fail and creates rereplication
tasks for the ledgers on failed bookies.
+1. The [**replication worker**](#replication-worker) (see the [`ReplicationWorker`](../../api/javadoc/org/apache/bookkeeper/replication/ReplicationWorker.html)
class) runs on each bookie and executes rereplication tasks provided by the auditor.
 
-Both of these components run as threads in the [`AutoRecoveryMain`]({{ site.baseurl }}javadoc/org/apache/bookkeeper/replication/AutoRecoveryMain)
process, which runs on each bookie in the cluster. All recovery nodes participate in leader
election---using ZooKeeper---to decide which node becomes the auditor. Nodes that fail to
become the auditor watch the elected auditor and run an election process again if they see
that the auditor node has failed.
+Both of these components run as threads in the [`AutoRecoveryMain`](../../api/javadoc/org/apache/bookkeeper/replication/AutoRecoveryMain)
process, which runs on each bookie in the cluster. All recovery nodes participate in leader
election---using ZooKeeper---to decide which node becomes the auditor. Nodes that fail to
become the auditor watch the elected auditor and run an election process again if they see
that the auditor node has failed.
 
 ### Auditor
 
@@ -125,4 +125,4 @@ The ledger rereplication process happens in these steps:
    1. Once all entries have been replicated, the zookeeper metadata for the segment is updated
to reflect the new ensemble.
    1. The segment is marked as fully replicated in the recovery tool.
 1. Once all ledger segments are marked as fully replicated, the ledger is marked as fully
replicated.
-  
\ No newline at end of file
+  
diff --git a/site/docs/admin/bookies.md b/site/docs/latest/admin/bookies.md
similarity index 100%
rename from site/docs/admin/bookies.md
rename to site/docs/latest/admin/bookies.md
diff --git a/site/docs/admin/geo-replication.md b/site/docs/latest/admin/geo-replication.md
similarity index 100%
rename from site/docs/admin/geo-replication.md
rename to site/docs/latest/admin/geo-replication.md
diff --git a/site/docs/admin/metrics.md b/site/docs/latest/admin/metrics.md
similarity index 100%
rename from site/docs/admin/metrics.md
rename to site/docs/latest/admin/metrics.md
diff --git a/site/docs/admin/perf.md b/site/docs/latest/admin/perf.md
similarity index 100%
rename from site/docs/admin/perf.md
rename to site/docs/latest/admin/perf.md
diff --git a/site/docs/admin/placement.md b/site/docs/latest/admin/placement.md
similarity index 100%
rename from site/docs/admin/placement.md
rename to site/docs/latest/admin/placement.md
diff --git a/site/docs/api/distributedlog-api.md b/site/docs/latest/api/distributedlog-api.md
similarity index 98%
rename from site/docs/api/distributedlog-api.md
rename to site/docs/latest/api/distributedlog-api.md
index 71c2db1..0b12e1d 100644
--- a/site/docs/api/distributedlog-api.md
+++ b/site/docs/latest/api/distributedlog-api.md
@@ -13,7 +13,7 @@ DistributedLog (DL) maintains sequences of records in categories called
*logs* (
 
 The diagram below illustrates how the DistributedLog API works with BookKeeper:
 
-![DistributedLog API]({{ site.baseurl }}img/distributedlog.png)
+![DistributedLog API](../../../img/distributedlog.png)
 
 ## Logs
 
@@ -21,7 +21,7 @@ A *log* in DistributedLog is an ordered, immutable sequence of *log records*.
 
 The diagram below illustrates the anatomy of a log stream:
 
-![DistributedLog log]({{ site.baseurl }}img/logs.png)
+![DistributedLog log](../../../img/logs.png)
 
 ### Log records
 
@@ -115,12 +115,12 @@ If you're using [Gradle](https://gradle.org/), add this to your [`build.gradle`]
 
 ```groovy
 dependencies {
-    compile group: 'org.apache.bookkeeper', name: 'bookkeeper-server', version: '{{ site.bk_version
}}'
+    compile group: 'org.apache.bookkeeper', name: 'bookkeeper-server', version: '{{ site.latest_version
}}'
 }
 
 // Alternatively:
 dependencies {
-    compile 'org.apache.bookkeeper:bookkeeper-server:{{ site.bk_version }}'
+    compile 'org.apache.bookkeeper:bookkeeper-server:{{ site.latest_version }}'
 }
 ```
 
@@ -392,4 +392,4 @@ FutureUtils.result(asyncWriter.asyncClose());
 
 <!--
 TODO: Reader API
--->
\ No newline at end of file
+-->
diff --git a/site/docs/api/ledger-api.md b/site/docs/latest/api/ledger-api.md
similarity index 96%
rename from site/docs/api/ledger-api.md
rename to site/docs/latest/api/ledger-api.md
index 3d47de2..255ef80 100644
--- a/site/docs/api/ledger-api.md
+++ b/site/docs/latest/api/ledger-api.md
@@ -20,7 +20,7 @@ If you're using [Maven](https://maven.apache.org/), add this to your [`pom.xml`]
 
 ```xml
 <!-- in your <properties> block -->
-<bookkeeper.version>{{ site.bk_version }}</bookkeeper.version>
+<bookkeeper.version>{{ site.latest_version }}</bookkeeper.version>
 
 <!-- in your <dependencies> block -->
 <dependency>
@@ -36,12 +36,12 @@ If you're using [Gradle](https://gradle.org/), add this to your [`build.gradle`]
 
 ```groovy
 dependencies {
-    compile group: 'org.apache.bookkeeper', name: 'bookkeeper-server', version: '{{ site.bk_version
}}'
+    compile group: 'org.apache.bookkeeper', name: 'bookkeeper-server', version: '{{ site.latest_version
}}'
 }
 
 // Alternatively:
 dependencies {
-    compile 'org.apache.bookkeeper:bookkeeper-server:{{ site.bk_version }}'
+    compile 'org.apache.bookkeeper:bookkeeper-server:{{ site.latest_version }}'
 }
 ```
 
@@ -55,7 +55,7 @@ When interacting with BookKeeper using the Java client, you need to provide
your
 
 ## Creating a new client
 
-In order to create a new [`BookKeeper`](/javadoc/org/apache/bookkeeper/client/BookKeeper)
client object, you need to pass in a [connection string](#connection-string). Here is an example
client object using a ZooKeeper connection string:
+In order to create a new [`BookKeeper`](../javadoc/org/apache/bookkeeper/client/BookKeeper)
client object, you need to pass in a [connection string](#connection-string). Here is an example
client object using a ZooKeeper connection string:
 
 ```java
 try {
@@ -70,7 +70,7 @@ try {
 
 There are, however, other ways that you can create a client object:
 
-* By passing in a [`ClientConfiguration`](/javadoc/org/apache/bookkeeper/conf/ClientConfiguration)
object. Here's an example:
+* By passing in a [`ClientConfiguration`](../javadoc/org/apache/bookkeeper/conf/ClientConfiguration)
object. Here's an example:
 
   ```java
   ClientConfiguration config = new ClientConfiguration();
@@ -96,7 +96,7 @@ There are, however, other ways that you can create a client object:
 
 ## Creating ledgers
 
-The easiest way to create a {% pop ledger %} using the Java client is via the `createLedger`
method, which creates a new ledger synchronously and returns a [`LedgerHandle`](/javadoc/org/apache/bookkeeper/client/LedgerHandle).
You must specify at least a [`DigestType`](/javadoc/org/apache/bookkeeper/client/BookKeeper.DigestType)
and a password.
+The easiest way to create a {% pop ledger %} using the Java client is via the `createLedger`
method, which creates a new ledger synchronously and returns a [`LedgerHandle`](../javadoc/org/apache/bookkeeper/client/LedgerHandle).
You must specify at least a [`DigestType`](../javadoc/org/apache/bookkeeper/client/BookKeeper.DigestType)
and a password.
 
 Here's an example:
 
diff --git a/site/docs/api/overview.md b/site/docs/latest/api/overview.md
similarity index 100%
rename from site/docs/api/overview.md
rename to site/docs/latest/api/overview.md
diff --git a/site/docs/deployment/dcos.md b/site/docs/latest/deployment/dcos.md
similarity index 94%
rename from site/docs/deployment/dcos.md
rename to site/docs/latest/deployment/dcos.md
index ca5cf60..da8b115 100644
--- a/site/docs/deployment/dcos.md
+++ b/site/docs/latest/deployment/dcos.md
@@ -41,25 +41,25 @@ The bookie that is automatically started up uses the host mode of the
network an
 
 To watch BookKeeper start up, click on the **Services** tab in the DC/OS [user interface](https://docs.mesosphere.com/latest/gui/)
and you should see the `bookkeeper` package listed:
 
-![DC/OS services]({{ site.baseurl }}img/dcos/services.png)
+![DC/OS services](../../../img/dcos/services.png)
 
 ### Tasks
 
 To see which tasks have started, click on the `bookkeeper` service and you'll see an interface
that looks like this;
 
-![DC/OS tasks]({{ site.baseurl }}img/dcos/tasks.png)
+![DC/OS tasks](../../../img/dcos/tasks.png)
 
 ## Scaling BookKeeper
 
 Once the first {% pop bookie %} has started up, you can click on the **Scale** tab to scale
up your BookKeeper ensemble by adding more bookies (or scale down the ensemble by removing
bookies).
 
-![DC/OS scale]({{ site.baseurl }}img/dcos/scale.png)
+![DC/OS scale](../../../img/dcos/scale.png)
 
 ## ZooKeeper Exhibitor
 
 ZooKeeper contains the information for all bookies in the ensemble. When deployed on DC/OS,
BookKeeper uses a ZooKeeper instance provided by DC/OS. You can access a visual UI for ZooKeeper
using [Exhibitor](https://github.com/soabase/exhibitor/wiki), which is available at [http://master.dcos/exhibitor](http://master.dcos/exhibitor).
 
-![ZooKeeper Exhibitor]({{ site.baseurl }}img/dcos/exhibitor.png)
+![ZooKeeper Exhibitor](../../../img/dcos/exhibitor.png)
 
 You should see a listing of IP/host information for all bookies under the `messaging/bookkeeper/ledgers/available`
node.
 
@@ -137,6 +137,6 @@ You can shut down and uninstall the `bookkeeper` from DC/OS at any time
using th
 
 ```shell
 $ dcos package uninstall bookkeeper
-Uninstalled package [bookkeeper] version [{{ site.bk_version }}]
+Uninstalled package [bookkeeper] version [{{ site.latest_version }}]
 Thank you for using bookkeeper.
 ```
diff --git a/site/docs/deployment/kubernetes.md b/site/docs/latest/deployment/kubernetes.md
similarity index 100%
rename from site/docs/deployment/kubernetes.md
rename to site/docs/latest/deployment/kubernetes.md
diff --git a/site/docs/deployment/manual.md b/site/docs/latest/deployment/manual.md
similarity index 100%
rename from site/docs/deployment/manual.md
rename to site/docs/latest/deployment/manual.md
diff --git a/site/docs/development/codebase.md b/site/docs/latest/development/codebase.md
similarity index 100%
rename from site/docs/development/codebase.md
rename to site/docs/latest/development/codebase.md
diff --git a/site/docs/development/protocol.md b/site/docs/latest/development/protocol.md
similarity index 100%
rename from site/docs/development/protocol.md
rename to site/docs/latest/development/protocol.md
diff --git a/site/docs/example.md b/site/docs/latest/example.md
similarity index 100%
rename from site/docs/example.md
rename to site/docs/latest/example.md
diff --git a/site/docs/getting-started/concepts.md b/site/docs/latest/getting-started/concepts.md
similarity index 90%
rename from site/docs/getting-started/concepts.md
rename to site/docs/latest/getting-started/concepts.md
index 5c86830..7a3c928 100644
--- a/site/docs/getting-started/concepts.md
+++ b/site/docs/latest/getting-started/concepts.md
@@ -1,8 +1,7 @@
 ---
 title: BookKeeper concepts and architecture
 subtitle: The core components and how they work
-prev: /docs/getting-started/run-locally
-next: /docs/applications/java-client
+prev: ../run-locally
 ---
 
 BookKeeper is a service that provides persistent storage of streams of log [entries](#entries)---aka
*records*---in sequences called [ledgers](#ledgers). BookKeeper replicates stored entries
across multiple servers.
@@ -159,7 +158,7 @@ The data compaction flow in the garbage collector thread is as follows:
 
 ## ZooKeeper metadata
 
-BookKeeper requires a ZooKeeper installation for storing [ledger](#ledger) metadata. Whenever
you construct a [`BookKeeper`](/javadoc/org/apache/bookkeeper/client/BookKeeper) client object,
you need to pass a list of ZooKeeper servers as a parameter to the constructor, like this:
+BookKeeper requires a ZooKeeper installation for storing [ledger](#ledger) metadata. Whenever
you construct a [`BookKeeper`](../../api/javadoc/org/apache/bookkeeper/client/BookKeeper)
client object, you need to pass a list of ZooKeeper servers as a parameter to the constructor,
like this:
 
 ```java
 String zkConnectionString = "127.0.0.1:2181";
@@ -170,14 +169,14 @@ BookKeeper bkClient = new BookKeeper(zkConnectionString);
 
 ## Ledger manager
 
-A *ledger manager* handles ledgers' metadata (which is stored in ZooKeeper). BookKeeper offers
two types of ledger managers: the [flat ledger manager](#flat-ledger-manager) and the [hierarchical
ledger manager](#hierarchical-ledger-manager). Both ledger managers extend the [`AbstractZkLedgerManager`](/javadoc/org/apache/bookkeeper/meta/AbstractZkLedgerManager)
abstract class.
+A *ledger manager* handles ledgers' metadata (which is stored in ZooKeeper). BookKeeper offers
two types of ledger managers: the [flat ledger manager](#flat-ledger-manager) and the [hierarchical
ledger manager](#hierarchical-ledger-manager). Both ledger managers extend the [`AbstractZkLedgerManager`](../../api/javadoc/org/apache/bookkeeper/meta/AbstractZkLedgerManager)
abstract class.
 
 > #### Use the flat ledger manager in most cases
 > The flat ledger manager is the default and is recommended for nearly all use cases.
The hierarchical ledger manager is better suited only for managing very large numbers of BookKeeper
ledgers (> 50,000).
 
 ### Flat ledger manager
 
-The *flat ledger manager*, implemented in the [`FlatLedgerManager`](/javadoc/org/apache/bookkeeper/meta/FlatLedgerManager.html)
class, stores all ledgers' metadata in child nodes of a single ZooKeeper path. The flat ledger
manager creates [sequential nodes](https://zookeeper.apache.org/doc/trunk/zookeeperProgrammers.html#Sequence+Nodes+--+Unique+Naming)
to ensure the uniqueness of the ledger ID and prefixes all nodes with `L`. Bookie servers
manage their own active ledgers in a hash map  [...]
+The *flat ledger manager*, implemented in the [`FlatLedgerManager`](../../api/javadoc/org/apache/bookkeeper/meta/FlatLedgerManager.html)
class, stores all ledgers' metadata in child nodes of a single ZooKeeper path. The flat ledger
manager creates [sequential nodes](https://zookeeper.apache.org/doc/trunk/zookeeperProgrammers.html#Sequence+Nodes+--+Unique+Naming)
to ensure the uniqueness of the ledger ID and prefixes all nodes with `L`. Bookie servers
manage their own active ledgers in a  [...]
 
 The flat ledger manager's garbage collection follow proceeds as follows:
 
@@ -188,7 +187,7 @@ The flat ledger manager's garbage collection follow proceeds as follows:
 
 ### Hierarchical ledger manager
 
-The *hierarchical ledger manager*, implemented in the [`HierarchicalLedgerManager`](/javadoc/org/apache/bookkeeper/meta/HierarchicalLedgerManager)
class, first obtains a global unique ID from ZooKeeper using an [`EPHEMERAL_SEQUENTIAL`](https://zookeeper.apache.org/doc/current/api/org/apache/zookeeper/CreateMode.html#EPHEMERAL_SEQUENTIAL)
znode. Since ZooKeeper's sequence counter has a format of `%10d` (10 digits with 0 padding,
for example `<path>0000000001`), the hierarchical ledger man [...]
+The *hierarchical ledger manager*, implemented in the [`HierarchicalLedgerManager`](../../api/javadoc/org/apache/bookkeeper/meta/HierarchicalLedgerManager)
class, first obtains a global unique ID from ZooKeeper using an [`EPHEMERAL_SEQUENTIAL`](https://zookeeper.apache.org/doc/current/api/org/apache/zookeeper/CreateMode.html#EPHEMERAL_SEQUENTIAL)
znode. Since ZooKeeper's sequence counter has a format of `%10d` (10 digits with 0 padding,
for example `<path>0000000001`), the hierarchical l [...]
 
 ```shell
 {level1 (2 digits)}{level2 (4 digits)}{level3 (4 digits)}
diff --git a/site/docs/getting-started/installation.md b/site/docs/latest/getting-started/installation.md
similarity index 93%
rename from site/docs/getting-started/installation.md
rename to site/docs/latest/getting-started/installation.md
index 914ba47..ed77bce 100644
--- a/site/docs/getting-started/installation.md
+++ b/site/docs/latest/getting-started/installation.md
@@ -1,10 +1,10 @@
 ---
 title: BookKeeper installation
 subtitle: Download or clone BookKeeper and build it locally
-next: /docs/getting-started/run-locally
+next: ../run-locally
 ---
 
-{% capture download_url %}http://apache.claz.org/bookkeeper/bookkeeper-{{ site.bk_version
}}/bookkeeper-{{ site.bk_version }}-src.tar.gz{% endcapture %}
+{% capture download_url %}http://apache.claz.org/bookkeeper/bookkeeper-{{ site.stable_release
}}/bookkeeper-{{ site.stable_release }}-src.tar.gz{% endcapture %}
 
 You can install BookKeeper either by [downloading](#download) a [GZipped](http://www.gzip.org/)
tarball package or [cloning](#clone) the BookKeeper repository.
 
@@ -20,8 +20,8 @@ You can download Apache BookKeeper releases from one of many [Apache mirrors](ht
 
 ```shell
 $ curl -O {{ download_url }}
-$ tar xvf bookkeeper-{{ site.bk_version }}-src.tar.gz
-$ cd bookkeeper-{{ site.bk_version }}
+$ tar xvf bookkeeper-{{ site.stable_release }}-src.tar.gz
+$ cd bookkeeper-{{ site.stable_release }}
 ```
 
 ## Clone
diff --git a/site/docs/getting-started/run-locally.md b/site/docs/latest/getting-started/run-locally.md
similarity index 87%
rename from site/docs/getting-started/run-locally.md
rename to site/docs/latest/getting-started/run-locally.md
index 691b918..ab33642 100644
--- a/site/docs/getting-started/run-locally.md
+++ b/site/docs/latest/getting-started/run-locally.md
@@ -1,7 +1,7 @@
 ---
 title: Run bookies locally
-prev: /docs/getting-started/installation
-next: /docs/getting-started/concepts
+prev: ../installation
+next: ../concepts
 toc_disable: true
 ---
 
diff --git a/site/docs/latest/index.md b/site/docs/latest/index.md
new file mode 100644
index 0000000..132cdd3
--- /dev/null
+++ b/site/docs/latest/index.md
@@ -0,0 +1,57 @@
+---
+title: Apache BookKeeper 4.5.0-SNAPSHOT Documentation 
+layout: community
+---
+<!--
+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.
+-->
+
+This documentation is for Apache BookKeeper version `{{ site.latest_version }}`.
+
+Apache BookKeeper is a scalable, fault tolerant and low latency storage service optimized
for realtime workloads.
+It offers `durability`, `replication` and `strong consistency` as essentials for building
reliable real-time applications.
+
+It is suitable for being used in following scenerios:
+
+- [WAL](https://en.wikipedia.org/wiki/Write-ahead_logging) (Write-Ahead-Logging), e.g. HDFS
[namenode](https://hadoop.apache.org/docs/r2.5.2/hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithNFS.html#BookKeeper_as_a_Shared_storage_EXPERIMENTAL).
+- Message Store, e.g. [Apache Pulsar](https://pulsar.incubator.apache.org/).
+- Offset/Cursor Store, e.g. Apache Pulsar.
+- Object/Blob Store, e.g. storing snapshots to replicated state machines.
+
+Learn more about Apache BookKeeper and what it can do for your organization:
+
+- [Apache BookKeeper {{ site.latest_version }} Release Notes](./releaseNotes)
+
+Or start using Apache BookKeeper today.
+
+### Users 
+
+- **Concepts**: Start with [concepts](./getting-started/concepts). This will help you to
fully understand
+    the other parts of the documentation, including the setup, integration and operation
guides.
+- **Getting Started**: Install [Apache BookKeeper](./getting-started/installation) and run
bookies [locally](./getting-started/run-locally)
+- **API**: Read the [API](./api/overview) documentation to learn how to use Apache BookKeeper
to build your applications.
+- **Deployment**: The [Deployment Guide](./deployment/manual) shows how to deploy Apache
BookKeeper to production clusters.
+
+### Administrators
+
+- **Operations**: The [Admin Guide](./admin) shows how to run Apache BookKeeper on production,
what are the production
+    considerations and best practices.
+
+### Contributors
+
+- **Details**: Learn [design details](./development/protocol) to know more internals.
diff --git a/site/docs/reference/cli.md b/site/docs/latest/reference/cli.md
similarity index 100%
rename from site/docs/reference/cli.md
rename to site/docs/latest/reference/cli.md
diff --git a/site/docs/reference/config.md b/site/docs/latest/reference/config.md
similarity index 100%
rename from site/docs/reference/config.md
rename to site/docs/latest/reference/config.md
diff --git a/site/docs/reference/metrics.md b/site/docs/latest/reference/metrics.md
similarity index 100%
rename from site/docs/reference/metrics.md
rename to site/docs/latest/reference/metrics.md
diff --git a/site/docs/latest/releaseNotes.md b/site/docs/latest/releaseNotes.md
new file mode 100644
index 0000000..82c14c1
--- /dev/null
+++ b/site/docs/latest/releaseNotes.md
@@ -0,0 +1,13 @@
+---
+title: Apache BookKeeper 4.5.0-SNAPSHOT Release Notes
+layout: community
+---
+
+Apache BookKeeper {{ site.latest_version }} is still under developement.
+
+If you want to learn the progress of `{{ site.latest_version }}`, you can do:
+
+- Track the progress by following the [issues](https://github.com/apache/bookkeeper/issues)
on Github.
+- Or [subscribe](mailto:dev-subscribe@bookkeeper.apache.org) the [dev@bookkeeper.apache.org](mailto:dev@bookkeeper.apache.org)
+    to join development discussions, propose new ideas and connect with contributors.
+- Or [join us on Slack](https://apachebookkeeper.herokuapp.com/) to connect with Apache BookKeeper
committers and contributors.
diff --git a/site/docs/latest/releaseNotesTemplate.md b/site/docs/latest/releaseNotesTemplate.md
new file mode 100644
index 0000000..5aa16aa
--- /dev/null
+++ b/site/docs/latest/releaseNotesTemplate.md
@@ -0,0 +1,18 @@
+---
+title: Apache BookKeeper 4.5.0-SNAPSHOT Release Notes
+layout: community
+---
+
+[provide a summary of this release]
+
+Apache BookKeeper users are encouraged to upgrade to `{{ site.latest_version }}`. The technical
details of this release are summarized
+below.
+
+## Highlights
+
+[List the highlights]
+
+## Details
+
+[list to issues list]
+
diff --git a/site/index.html b/site/index.html
index b7a586c..b0726b7 100644
--- a/site/index.html
+++ b/site/index.html
@@ -27,7 +27,7 @@ title: Home
                 <nav class="level is-mobile">
                   <div class="level-left">
                     <div class="level-item">
-                      <a class="button is-primary is-large" href="{{ site.baseurl }}docs/getting-started/installation">
+                      <a class="button is-primary is-large" href="{{ site.baseurl }}docs/latest/getting-started/installation">
                         <span class="icon">
                           <i class="fa fa-download"></i>
                         </span>
@@ -53,4 +53,4 @@ title: Home
 
     {% include footer.html %}
   </body>
-</html>
\ No newline at end of file
+</html>
diff --git a/site/releases.md b/site/releases.md
index 708a90b..c54419c 100644
--- a/site/releases.md
+++ b/site/releases.md
@@ -5,7 +5,7 @@ layout: community
 
 ## Download
 
-{{ site.stable_release }} is latest release. The current stable version is {{ site.stable_release
}}.
+{{ site.latest_release }} is latest release. The current stable version is {{ site.stable_release
}}.
 
 Releases are available to download from Apache mirrors: [Download](http://www.apache.org/dyn/closer.cgi/bookkeeper)
 
@@ -16,14 +16,14 @@ If you want to download older releases, they are available in the [Apache
archiv
 ## Getting Started
 
 Once you've downloaded a BookKeeper release, instructions on getting up and running with
a standalone cluster that you can run your laptop can be found
-in [Run BookKeeper locally]({{ site.baseurl }}docs/getting-started/run-locally).
+in [Run BookKeeper locally]({{ site.baseurl }}docs/latest/getting-started/run-locally).
 
 If you need to connect to an existing BookKeeper cluster using an officially supported client,
see client docs for these languages:
 
 Client Guide | API docs
 :------------|:--------
-[The BookKeeper Client]({{ site.baseurl }}docs/api/ledger-api) | [Javadoc]({{ site.baseurl
}}javadoc)
-[The DistributedLog Library]({{ site.baseurl }}docs/api/distributedlog-api) | [Javadoc](https://distributedlog.io/docs/latest/api/java)
+[The BookKeeper Client]({{ site.baseurl }}docs/latest/api/ledger-api) | [Javadoc]({{ site.baseurl
}}docs/latest/api/javadoc)
+[The DistributedLog Library]({{ site.baseurl }}docs/latest/api/distributedlog-api) | [Javadoc](https://distributedlog.io/docs/latest/api/java)
 
 ## News
 
@@ -34,7 +34,7 @@ This is the fourth release of BookKeeper as an Apache Top Level Project!
 This release contains a total of 94 Jira tickets fixed and brings several bookie
 reliability and operability improvements, along with a long list of bugfixes.
 
-See [BookKeeper 4.4.0 Release Notes]({{ site.baseurl }}docs/r4.4.0/releaseNotes.html) for
details.
+See [BookKeeper 4.4.0 Release Notes]({{ site.baseurl }}archives/docs/r4.4.0/releaseNotes.html)
for details.
 
 ### 30 Nov, 2015: release 4.3.2 available
 
@@ -42,7 +42,7 @@ This is the third release of BookKeeper as an Apache Top Level Project!
 
 This release fixes some issues in both bookie server and bookkeeper client.
 
-See [BookKeeper 4.3.2 Release Notes]({{ site.baseurl }}docs/r4.3.2/releaseNotes.html) for
details.
+See [BookKeeper 4.3.2 Release Notes]({{ site.baseurl }}archives/docs/r4.3.2/releaseNotes.html)
for details.
 
 ### 27 May, 2015: release 4.3.1 available
 
@@ -50,7 +50,7 @@ This is the second release of BookKeeper as an Apache Top Level Project!
 
 This release fixes some issues in both bookie server and bookkeeper client.
 
-See [BookKeeper 4.3.1 Release Notes]({{ site.baseurl }}docs/r4.3.1/releaseNotes.html) for
details.
+See [BookKeeper 4.3.1 Release Notes]({{ site.baseurl }}archives/docs/r4.3.1/releaseNotes.html)
for details.
 
 ### 16 Jan, 2015: release 4.2.4 available
 
@@ -58,7 +58,7 @@ This is the first release of BookKeeper as an Apache Top Level Project!
 
 This release fixes some critical issues in fencing when the ack quorum and write quorum are
different sizes.
 
-See [BookKeeper 4.2.4 Release Notes]({{ site.baseurl }}docs/r4.2.4/releaseNotes.html) for
details.
+See [BookKeeper 4.2.4 Release Notes]({{ site.baseurl }}archives/docs/r4.2.4/releaseNotes.html)
for details.
 
 ### 14 Oct, 2014: release 4.3.0 available
 
@@ -66,7 +66,7 @@ This is the seventh release of BookKeeper as a subproject of Zookeeper.
 
 This release includes a lot of improvements to the bookie on-disk performance, a new statistics
framework, and protobuffer protocol support along with numerous bugfixes.
 
-See [BookKeeper 4.3.0 Release Notes]({{ site.baseurl }}docs/r4.3.0/releaseNotes.html) for
details.
+See [BookKeeper 4.3.0 Release Notes]({{ site.baseurl }}archives/docs/r4.3.0/releaseNotes.html)
for details.
 
 ### 27 June, 2013: release 4.2.3 available
 
@@ -79,7 +79,7 @@ improvements to allow for smoother rolling upgrades (BOOKKEEPER-745),
 fixes to ledger polling to ensure metadata updates aren't missed (BOOKKEEPER-710 & BOOKKEEPER-747)
and shading of protobuf libraries
 to avoid conflicts when included with other version (BOOKKEEPER-708).
 
-See [BookKeeper 4.2.3 Release Notes]({{ site.baseurl }}docs/r4.2.3/releaseNotes.html) for
details.
+See [BookKeeper 4.2.3 Release Notes]({{ site.baseurl }}archives/docs/r4.2.3/releaseNotes.html)
for details.
 
 ### 9 Oct, 2013: release 4.2.2 available
 
@@ -87,27 +87,27 @@ This is the fifth release of BookKeeper as a subproject of Zookeeper.
 
 This is a bugfix release for 4.2.1. There are some minor API improvements. Notably, it is
now possible to check whether a ledger is closed without opening it, and it is now possible
to get a list of ledgers available in the cluster.
 
-See [BookKeeper 4.2.2 Release Notes]({{ site.baseurl }}docs/r4.2.2/releaseNotes.html) for
details.
+See [BookKeeper 4.2.2 Release Notes]({{ site.baseurl }}archives/docs/r4.2.2/releaseNotes.html)
for details.
 
 ### 27 Feb, 2013: release 4.2.1 available
 
 This is the fourth release of BookKeeper as a subproject of Zookeeper.
 *This release fixes a major performance bug in release 4.2.0. All users of BookKeeper 4.2.0
should upgrade immediately.*
 
-See [BookKeeper 4.2.1 Release Notes]({{ site.baseurl }}docs/r4.2.1/releaseNotes.html) for
details.
+See [BookKeeper 4.2.1 Release Notes]({{ site.baseurl }}archives/docs/r4.2.1/releaseNotes.html)
for details.
 
 ### 18 Jan, 2013: release 4.2.0 available
 
 This is the third release of BookKeeper as a subproject of Zookeeper.
-See [BookKeeper 4.2.0 Release Notes]({{ site.baseurl }}docs/r4.2.0/releaseNotes.html) for
details.
+See [BookKeeper 4.2.0 Release Notes]({{ site.baseurl }}archives/docs/r4.2.0/releaseNotes.html)
for details.
 
 ### 12 Jun, 2012: release 4.1.0 available
 
 This is the second release of BookKeeper as a subproject of Zookeeper.
-See [BookKeeper 4.1.0 Release Notes]({{ site.baseurl }}docs/r4.1.0/releaseNotes.html) for
details.
+See [BookKeeper 4.1.0 Release Notes]({{ site.baseurl }}archives/docs/r4.1.0/releaseNotes.html)
for details.
 
 ### 7 Dec, 2011: release 4.0.0 available
 
 This is the first release of BookKeeper as a subproject of Zookeeper.
-See [BookKeeper 4.0.0 Release Notes]({{ site.baseurl }}docs/r4.0.0/releaseNotes.html) for
details.
+See [BookKeeper 4.0.0 Release Notes]({{ site.baseurl }}archives/docs/r4.0.0/releaseNotes.html)
for details.
 
diff --git a/site/scripts/common.sh b/site/scripts/common.sh
index ae8e9b4..e92740f 100755
--- a/site/scripts/common.sh
+++ b/site/scripts/common.sh
@@ -1,9 +1,10 @@
 #!/bin/bash
 
+DOC_VERSION=${DOC_VERSION:-"latest"}
 ROOT_DIR=$(git rev-parse --show-toplevel)
 REVISION=$(git rev-parse --short HEAD)
 JAVADOC_GEN_DIR=${JAVADOC_GEN_DIR:-"target/site/apidocs"}
-JAVADOC_DEST_DIR=${JAVADOC_DEST_DIR:-"site/javadoc"}
+JAVADOC_DEST_DIR=${JAVADOC_DEST_DIR:-"site/docs/${DOC_VERSION}/api/javadoc"}
 LOCAL_GENERATED_DIR=$ROOT_DIR/site/local-generated
 APACHE_GENERATED_DIR=$ROOT_DIR/site/generated_site
 TMP_DIR=/tmp/bookkeeper-site
diff --git a/site/scripts/release.sh b/site/scripts/release.sh
new file mode 100755
index 0000000..215964e
--- /dev/null
+++ b/site/scripts/release.sh
@@ -0,0 +1,88 @@
+#!/bin/bash
+#
+# 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.
+#
+
+source scripts/common.sh
+
+BINDIR=`dirname "$0"`
+DOC_HOME=`cd $BINDIR/..;pwd`
+
+LATEST_VERSION=`grep latest_version _config.yml | sed 's/^latest_version: "\(.*\)"/\1/'`
+LATEST_RELEASE=`grep latest_release _config.yml | sed 's/^latest_release: "\(.*\)"/\1/'`
+
+if [[ $LATEST_VERSION =~ "*-SNAPSHOT" ]]; then
+  echo "Latest version is not a SNAPSHOT version : $LATEST_VERSION"
+  exit 1
+fi
+
+RELEASE_VERSION=`echo $LATEST_VERSION | sed 's/^\(.*\)-SNAPSHOT/\1/'`
+
+echo "Releasing version $RELEASE_VERSION ..."
+
+# create a release directory
+
+if [[ -d ${DOC_HOME}/docs/${RELEASE_VERSION} ]]; then
+  echo "Release $RELEASE_VERSION docs dir '${DOC_HOME}/docs/${RELEASE_VERSION}' already exists."
+  exit 1
+fi
+
+cp -r ${DOC_HOME}/docs/latest ${DOC_HOME}/docs/${RELEASE_VERSION}
+
+# add the release to git repo
+git add ${DOC_HOME}/docs/${RELEASE_VERSION}
+
+cd ${DOC_HOME}/docs/${RELEASE_VERSION}
+
+find . -name "*.md" | xargs sed -i'.bak' "s/{{ site\.latest_version }}/${RELEASE_VERSION}/"
+find . -name "*.md" | xargs sed -i'.bak' "s/${LATEST_VERSION}/${RELEASE_VERSION}/"
+find . -name "*.md.bak" | xargs rm
+cp releaseNotesTemplate.md releaseNotes.md
+
+# go to doc home
+
+cd ${DOC_HOME}
+
+# insert release section
+find releases.md | xargs sed -i'.bak' "/## News/r _data/releaseNotesSummary.template"
+find releases.md | xargs sed -i'.bak' "s/{{ site\.latest_version }}/${RELEASE_VERSION}/"
+rm releases.md.bak
+
+# bump the version in _config.yml
+echo "- \"${RELEASE_VERSION}\"" > /tmp/bk_release_version
+find _config.yml | xargs sed -i'.bak' "/^versions:/r /tmp/bk_release_version"
+
+versions_list=(`echo $RELEASE_VERSION | tr '.' ' '`)
+major_version=${versions_list[0]}
+minor_version=${versions_list[1]}
+patch_version=${versions_list[2]}
+next_minor_version=$((minor_version + 1))
+NEXT_VERSION="${major_version}.${next_minor_version}.0-SNAPSHOT"
+find _config.yml | xargs sed -i'.bak' "s/latest_version: \"${LATEST_VERSION}\"/latest_version:
\"${NEXT_VERSION}\"/"
+find _config.yml | xargs sed -i'.bak' "s/latest_release: \"${LATEST_RELEASE}\"/latest_release:
\"${RELEASE_VERSION}\"/"
+
+rm _config.yml.bak
+
+# go to the latest doc home
+
+cd ${DOC_HOME}/docs/latest
+
+find . -name "*.md" | xargs sed -i'.bak' "s/${LATEST_VERSION}/${NEXT_VERSION}/"
+find . -name "*.md.bak" | xargs rm
+
+echo "Released version $RELEASE_VERSION."

-- 
To stop receiving notification emails like this one, please contact
['"commits@bookkeeper.apache.org" <commits@bookkeeper.apache.org>'].

Mime
View raw message