This is an automated email from the ASF dual-hosted git repository.
ivank 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 87ffad9 BP-20: Github workflow for bookkeeper proposals
87ffad9 is described below
commit 87ffad969c160b0e82944a6638f1710347b0bbeb
Author: Sijie Guo <si...@apache.org>
AuthorDate: Wed Nov 29 13:04:08 2017 +0100
BP-20: Github workflow for bookkeeper proposals
Descriptions of the changes in this PR:
Implementing a github workflow for bookkeeper proposals, so all the
bookkeeper proposals can be reviewed as code changes, and they can be
maintained in the same way as how we maintain documentation.
Author: Sijie Guo <si...@apache.org>
Reviewers: Ivan Kelly <iv...@apache.org>, Enrico Olivelli
<eolive...@gmail.com>, Jia Zhai <zhaiji...@gmail.com>
This closes #760 from sijie/BP_20
---
.github/ISSUE_TEMPLATE.md | 9 +-
.github/PULL_REQUEST_TEMPLATE.md | 9 ++
site/_config.yml | 4 +
site/_includes/navbar.html | 2 +-
...-20-github-workflow-for-bookkeeper-proposals.md | 46 +++++++++
site/bps/BP-template.md | 42 ++++++++
site/community/bookkeeper_proposals.md | 107 +++++++++++++++++++++
7 files changed, 217 insertions(+), 2 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
index 2505f24..02b03f2 100644
--- a/.github/ISSUE_TEMPLATE.md
+++ b/.github/ISSUE_TEMPLATE.md
@@ -1,4 +1,4 @@
-Is this a question, feature request, or bug report?
+Is this a question, feature request, bug report, or bookkeeper proposal?
**QUESTION**
@@ -29,3 +29,10 @@ Have you checked our documentation at
http://bookkeeper.apache.org/ , If you cou
- What did you see instead?
+**BP**
+
+This is the master ticket for tracking BP-<bp-number> :
+
+[a short description for this BP]
+
+Proposal PR - #<pr-number>
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index caca761..6b28945 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -5,6 +5,15 @@ Descriptions of the changes in this PR:
> ---
> Be sure to do all of the following to help us incorporate your contribution
> quickly and easily:
+>
+> If this PR is a BookKeeper Proposal (BP):
+>
+> - [ ] Make sure the PR title is formatted like:
+> `<BP-#>: Description of bookkeeper proposal`
+> `e.g. BP-1: 64 bits ledger is support`
+> - [ ] Attach the master issue link in the description of this PR.
+>
+> Otherwise:
>
> - [ ] Make sure the PR title is formatted like:
> `<Issue # or BOOKKEEPER-#>: Description of pull request`
diff --git a/site/_config.yml b/site/_config.yml
index 302c2e4..8810b8a 100644
--- a/site/_config.yml
+++ b/site/_config.yml
@@ -39,6 +39,10 @@ defaults:
layout: docs
toc: true
- scope:
+ path: bps
+ values:
+ layout: community
+- scope:
path: community
values:
layout: community
diff --git a/site/_includes/navbar.html b/site/_includes/navbar.html
index 349cdec..8121bf5 100644
--- a/site/_includes/navbar.html
+++ b/site/_includes/navbar.html
@@ -58,7 +58,7 @@
<a class="navbar-item" href="{{ site.baseurl
}}community/release_guide">Release Guide</a>
<hr class="dropdown-divider">
<a class="navbar-item" href="{{ site.baseurl
}}community/presentations">Presentations</a>
- <a class="navbar-item"
href="https://cwiki.apache.org/confluence/display/BOOKKEEPER/BookKeeper+Proposals";>BookKeeper
Proposals</a>
+ <a class="navbar-item" href="{{ site.baseurl
}}community/bookkeeper_proposals">BookKeeper Proposals</a>
</div>
</div>
diff --git a/site/bps/BP-20-github-workflow-for-bookkeeper-proposals.md
b/site/bps/BP-20-github-workflow-for-bookkeeper-proposals.md
new file mode 100644
index 0000000..8fa8b88
--- /dev/null
+++ b/site/bps/BP-20-github-workflow-for-bookkeeper-proposals.md
@@ -0,0 +1,46 @@
+---
+title: "BP-20: github workflow for bookkeeper proposals"
+issue: https://github.com/apache/bookkeeper/<issue-number>
+state: "Under Discussion"
+release: "N/A"
+---
+
+### Motivation
+
+We have a good BP process for introducing enhancements, features. However,
this process is not well integrated with our github review process, and the
content of a BP
+is not used for documentation. This proposal is to propose moving the BP
workflow from ASF wiki to Github. There are a couple of reasons for making this
change:
+
+- the ASF cwiki is disconnected from Github, and usually becomes out of date
quickly. It isn't really caught up with the code changes.
+ Most of the content (documentation, contribution/release guides) are already
in website, the ASF wiki is only used for tracking BPs and community meeting
notes at this point.
+- Moving BP workflow from wiki to github will leverage the same github review
process as code changes. So developers are easier to review BPs and make
comments.
+- The BPs can eventually be used as a basis for documentation.
+
+### Proposed Changes
+
+All the BPs are maintained in `site/bps` directory. To make a bookkeeper
proposal, a developer does following steps:
+
+1. Create an issue `BP-<number>: [capation of bookkeeper proposal]`. E.g.
`BP-1: 64 bits ledger id support`.
+ - Take the next available BP number from this page.
+ - Write a brief description about what BP is for in this issue. This issue
will be the master issue for tracking the status of this BP and its
implementations.
+ All the implementations of this BP should be listed and linked to this
master issues.
+1. Write the proposal for this BP.
+ - Make a copy of the
[BP-Template](https://github.com/apache/bookkeeper/tree/master/site/bps/BP-template.md).
Name the BP file as `BP-<number>-[caption-of-proposal].md`.
+ ```shell
+ $ cp site/bps/BP-template.md site/bps/BP-xyz-capation-of-proposal.md
+ ```
+ - Fill the sections listed in the BP template.
+ - issue: replace `<issue-number>` with the issue number.
+ - state: "Under Discussion"
+ - release: leave the release to `N/A`. you can only mark a release
after a BP is implemented.
+1. Send a PR for this BP. Following the instructions in the pull request
template.
+ - add `BP` label to this BP
+ - don't associate this PR with any release or milestone
+1. You can tag committers on this RP for reviewers, or start a `[DISCUSS]`
thread on Apache mailing list. If you are sending an email, please make sure
that the subject
+ of the thread is of the format `[DISCUSS] BP-<number>: capation of
bookkeeper proposal`.
+1. Once the BP is finalized, reviewed and approved by committers, the BP is
accepted. The criteria for acceptance is [lazy
majority](http://bookkeeper.apache.org/bylaws.html).
+1. Committers merge the PR after a BP is accepted. The development for this BP
moves forward with implementations. The BP should be updated if there is
anything changed during
+ implementing it.
+1. After all the implementations for a given BP are completed, a new PR should
be sent for changing the state of a BP:
+ - state: "Adopted"
+ - release: set to the release that includes this BP.
+1. The final PR for changing BP state will be used as the criteria for marking
a BP as completed.
diff --git a/site/bps/BP-template.md b/site/bps/BP-template.md
new file mode 100644
index 0000000..3207074
--- /dev/null
+++ b/site/bps/BP-template.md
@@ -0,0 +1,42 @@
+---
+title: "BP-XYZ: capation of bookkeeper proposal"
+issue: https://github.com/apache/bookkeeper/<issue-number>
+state: "one of ['Under Discussion', 'Accepted', 'Adopted', 'Rejected']"
+release: "x.y.z"
+---
+
+### Motivation
+
+_Describe the problems you are trying to solve_
+
+### Public Interfaces
+
+_Briefly list any new interfaces that will be introduced as part of this
proposal or any existing interfaces that will be removed or changed. The
purpose of this section is to concisely call out the public contract that will
come along with this feature._
+
+A public interface is any change to the following:
+
+- Data format, Metadata format
+- The wire protocol and api behavior
+- Any class in the public packages
+- Monitoring
+- Command line tools and arguments
+- Anything else that will likely break existing users in some way when they
upgrade
+
+### Proposed Changes
+
+_Describe the new thing you want to do in appropriate detail. This may be
fairly extensive and have large subsections of its own. Or it may be a few
sentences. Use judgement based on the scope of the change._
+
+### Compatibility, Deprecation, and Migration Plan
+
+- What impact (if any) will there be on existing users?
+- If we are changing behavior how will we phase out the older behavior?
+- If we need special migration tools, describe them here.
+- When will we remove the existing behavior?
+
+### Test Plan
+
+_Describe in few sentences how the BP will be tested. We are mostly interested
in system tests (since unit-tests are specific to implementation details). How
will we know that the implementation works as expected? How will we know
nothing broke?_
+
+### Rejected Alternatives
+
+_If there are alternative ways of accomplishing the same thing, what were
they? The purpose of this section is to motivate why the design is the way it
is and not some other way._
diff --git a/site/community/bookkeeper_proposals.md
b/site/community/bookkeeper_proposals.md
new file mode 100644
index 0000000..35a6ae8
--- /dev/null
+++ b/site/community/bookkeeper_proposals.md
@@ -0,0 +1,107 @@
+---
+title: BookKeeper Proposals
+---
+
+This page describes a proposed *BookKeeper Proposal (BP)* process for
proposing a major change to BookKeeper.
+
+## Process
+
+### What is considered a "major change" that needs a BP?
+
+Any of the following should be considered a major change:
+
+- Any major new feature, subsystem, or piece of functionality
+- Any change that impacts the public interfaces of the project
+- Any change that impacts developer workflow of the project
+
+All the following are public interfaces that people build around:
+
+- Binary log format
+- The network protocol and api behavior
+- Configuration, especially client configuration
+- Monitoring/Stats provider
+- Command line tools and arguments
+
+### What should be included in a BP?
+
+A BP should contain the following sections:
+
+- *Motivation*: describe the problem to be solved
+- *Proposed Change*: describe the new thing you want to do. This may be fairly
extensive and have large subsections of its own. Or it may be a few sentences,
depending on the scope of the change.
+- *New or Changed Public Interfaces*: impact to any of the "compatibility
commitments" described above. We want to call these out in particular so
everyone thinks about them.
+- *Migration Plan and Compatibility*: if this feature requires additional
support for a no-downtime upgrade describe how that will work
+- *Rejected Alternatives*: What are the other alternatives you considered and
why are they worse? The goal of this section is to help people understand why
this is the best solution now, and also to prevent churn in the future when old
alternatives are reconsidered.
+
+### Who should initiate the BP?
+
+Anyone can initiate a BP but you shouldn't do it unless you have an intention
of getting the work done to implement it (otherwise it is silly).
+
+### How to make a BP?
+
+Here is the process for making a BP:
+
+1. Create an issue `BP-<number>: [capation of bookkeeper proposal]`. E.g.
`BP-1: 64 bits ledger id support`.
+ - Take the next available BP number from this page.
+ - Write a brief description about what BP is for in this issue. This issue
will be the master issue for tracking the status of this BP and its
implementations.
+ All the implementations of this BP should be listed and linked to this
master issues.
+1. Write the proposal for this BP.
+ - Make a copy of the
[BP-Template](https://github.com/apache/bookkeeper/tree/master/site/bps/BP-template.md).
Name the BP file as `BP-<number>-[caption-of-proposal].md`.
+ ```shell
+ $ cp site/bps/BP-template.md site/bps/BP-xyz-capation-of-proposal.md
+ ```
+ - Fill the sections listed in the BP template.
+ - issue: replace `<issue-number>` with the issue number.
+ - state: "Under Discussion"
+ - release: leave the release to `N/A`. you can only mark a release
after a BP is implemented.
+1. Send a PR for this BP. Following the instructions in the pull request
template.
+ - add `BP` label to this BP
+ - don't associate this PR with any release or milestone
+1. You can tag committers on this RP for reviewers, or start a `[DISCUSS]`
thread on Apache mailing list. If you are sending an email, please make sure
that the subject
+ of the thread is of the format `[DISCUSS] BP-<number>: capation of
bookkeeper proposal`.
+1. Once the BP is finalized, reviewed and approved by committers, the BP is
accepted. The criteria for acceptance is [lazy
majority](http://bookkeeper.apache.org/bylaws.html).
+1. Committers merge the PR after a BP is accepted. The development for this BP
moves forward with implementations. The BP should be updated if there is
anything changed during
+ implementing it.
+1. After all the implementations for a given BP are completed, a new PR should
be sent for changing the state of a BP:
+ - state: "Adopted"
+ - release: set to the release that includes this BP.
+1. The final PR for changing BP state will be used as the criteria for marking
a BP as completed.
+
+## All Proposals
+
+This section lists all the _bookkeeper proposals_ made to BookKeeper.
+
+*Next Proposal Number: 21*
+
+### Inprogress
+
+Proposal | State
+:--------|:-----
+[BP-4 - BookKeeper Lifecycle
Management](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-4+-+BookKeeper+Lifecycle+Management)
| Draft
+[BP-8 - Queue based auto
rereplicator](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-8+-+Queue+based+auto+rereplicator)
| Draft
+[BP-12 - Improve
documentation](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-12+-+Improve+documentation)
| Accepted
+[BP-14 Relax
durability](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-14+Relax+durability)
| Accepted
+[BP-16: Thin Client - Remove direct metadata storage access from
clients](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-16%3A+Thin+Client+-+Remove+direct+metadata+storage+access+from+clients)
| Draft
+[BP-18: LedgerType, Flags and
StorageHints](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-18%3A+LedgerType%2C+Flags+and+StorageHints)
| Accepted
+[BP-20: Github workflow for bookkeeper
proposals](../../bps/BP-20-github-workflow-for-bookkeeper-proposals) | Under
Discussion
+
+### Adopted
+
+Proposal | Release
+:--------|:-------
+[BP-1 - 64 bits ledger id
support](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-1+-+64+bits+ledger+id+support)
| 4.5.0
+[BP-2 - Resource aware data
placement](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-2+-+Resource+aware+data+placement)
| 4.5.0
+[BP-3 - Security
support](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-3+-+Security+support)
| 4.5.0
+[BP-5 - Allow reads outside the LAC
Protocol](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-5+Allow+reads+outside+the+LAC+Protocol)
| 4.5.0
+[BP-6 - Use separate log for
compaction](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-6+-+Use+separate+log+for+compaction)
| 4.6.0
+[BP-9 - Github issues for Issue
Tracking](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-9+-+Github+issues+for+Issue+Tracking)
| 4.5.0
+[BP-10 - Official Bookkeeper Docker
Image](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-10+-+Official+Bookkeeper+Docker+Image)
| 4.5.0
+[BP-11 - Move website/documentation to Jekyll based
site](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=71012301)
| 4.5.0
+[BP-13 - Time Based Release
Plan](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-13+-+Time+Based+Release+Plan)
| 4.6.0
+[BP-15 - New CreateLedger
API](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-15+New+CreateLedger+API)
| 4.6.0
+[BP-17 - Define BookKeeper public http
endpoints](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-17%3A+Define+BookKeeper+public+http+endpoints)
| 4.6.0
+
+### Discarded
+
+Proposal | Reason
+:--------|:------
+[BP-7 - Explicit LAC on
addEntry](https://cwiki.apache.org/confluence/display/BOOKKEEPER/BP-7+-+Explicit+LAC+on+addEntry)
| Not A Problem
--
To stop receiving notification emails like this one, please contact
['"commits@bookkeeper.apache.org" <commits@bookkeeper.apache.org>'].
