Contributing to BookKeeper

This page documents the best way to make various types of contribution to Apache BookKeeper, including what is required before submitting a code change.

There may be bugs or possible improvements to this page, so please help us improve it. Credit to the Spark project. We've borrow liberally from their documentation.

Contributing to BookKeeper doesn't just mean writing code. Helping new users on the mailing list, testing releases, and improving documentation are also welcome. In fact, proposing significant code change usually requires first gaining experience and credibility within the community by helping in other ways. This is also a guide to becoming an effective contributor.

Overview

BookKeeper uses:

• JIRA to track logical issues, including bugs, tasks and improvements.
• Mailing Lists for proposing, planning, discussing changes
• Confluence for documentation
• Github pull requests or Review boards to manage the reviews and merge of specific code changes

That is, Mailing Lists are used for discussion and proposals, JIRA and Confluence are used to describe what should be fixed or changed and high-level approaches, and Pull Requests and Review Board describe how to implement the change in code.

Contributions

By Helping Other Users

Helping answer user questions on the user@bookkeeper.apache.org mailing list is the first way to contribute to BookKeeper. There are always many new BookKeeper users; taking a few minutes to help answer a question is very valuable community service.

Contributors should subscribe to this list and follow it in order to keep up to date on what's happing in BookKeeper. Answering questions is an excellent and visible way to help the community, which also demonstrates your expertise.

By Testing Releases

BookKeeper's release process is community-oriented, and members of the community can vote on new releases on the dev@bookkeeper.apache.org mailing list. BookKeeper users are encouraged to subscribe to this list to receive announcements (e.g the BookKeeper 4.3.1 release vote), and test their workloads on the newer release and provide feedback on any performance or correctness issues found in the newer release.

By Reviewing Changes 

Changes to BookKeeper source code are proposed, reviewed and committed via Pull Request or Review Board (described later). Anyone can view and comment on active changes here. Reviewing others' changes is a good way to learn how the change process works and again exposure to activity in various parts of the code. You can help by reviewing the changes and asking questions or pointing out issues – as simple as typos or small issues of style.

Documentation Changes

To have us add a link to an external tutorial you wrote, simply email to dev@bookkeeper.apache.org.

To modify the built-in documentation, checkout the instructions on How to build website and documentation.

Preparing to Contribute Code Changes

Before proceeding to code changes, contributors should evaluate if the proposed change is likely to be relevant, new and actionable:

• Is it clear that code must change? Proposing a JIRA and pull request is appropriate only when a clear problem or change has been identified. If simply having trouble using BookKeeper, use the mailing list first, rather than considering filing a JIRA or proposing a change. When in doubt, email user@bookkeeper.apache.org first about the possible change.
• Search the user@bookkeeper.apache.org and dev@bookkeeper.apache.org mailing list archives for related discussions. Often, the problem has been discussed before, with a resolution that doesn't require a code change, or recording what kind of changes will not be accepted as a resolution.
• Search JIRA for existing issues: https://issues.apache.org/jira/browse/BOOKKEEPER
  Type "bookkeeper [search terms]" at the top right search box. If a logically similar issue already exists, then contribute to the discussion on the existing JIRA and pull request first, instead of creating a new one.
• Is the scope of the change matched to the contributor's level of experience? Anyone is qualified to suggest a typo fix, but refactoring recovery logic requires much more understanding of BookKeeper. Some changes require building up experience first (see above).

Code Review Criteria

Before considering how to contribute code, it's useful to understand how code is reviewed, and why changes may be rejected. Simply put, changes that have many or large positives, and few negative effects or risks, are much more likely to be merged, and merged quickly. Risky and less valuable changes are very unlikely to be merged, and may be rejected outright rather than receive iterations of review.

Positives

• Fixes the root cause of a bug in existing functionality
• Adds functionality or fixes a problem needed by a large number of users
• Simple, targeted
• Has tests
• Reduces complexity and lines of code
• Change has already been discussed and is known to committers

Negatives

• Adds complexity that only helps a niche use case
• Changes a public API or semantics (rarely allowed)
• Makes lots of modifications in one "big bang" change
• Band-aids a symptom of a bug only

Contributing Code Changes

Please review the preceding section before proposing a code change. This section documents how to do so.

JIRA

1. Find the existing BookKeeper JIRA ticket that the change pertains to.
   1. Do not create a new JIRA ticket if creating a change to address an existing ticket in JIRA; add to the existing discussion and work instead.
   2. To avoid conflicts, assign the JIRA ticket to yourself if you plan to work on it.
   3. Look for existing pull requests or review boards that are linked from the the JIRA ticket, to understand if someone is already working on it.
2. If the change is new, then it usually needs a new JIRA ticket. However, trivial changes, where "what should change" is virtually the same as "how it should change" do not require a JIRA ticket. Example: "Fix typos in Foo javadoc"
3. If required, create a new JIRA ticket:
   1. Provide a descriptive Title. "Update web UI" or "Problem in ledger storage" is not sufficient. "Potential resource leak with unclosed LedgerManager in BookieShell" is good.
   2. Write a detailed description. For bug reports, this should ideally include a short reproduction of the problem. For new features, it may include a design document or a link to mailing list discussion.
   3. Set required fields:
      1. Issue Type. Generally, Bug, Improvement, New Feature, Documentation are the only types used in BookKeeper.
      2. Priority. Set to Major or below; higher priorities are generally reserved for committers to set. JIRA tends to unfortunately conflate "size" and "importance" in its Priority field values. Their meaning is roughly:

         1. Blocker: pointless to release without this change as the release would be unusable to a large minority of users

         2. Critical: a large minority of users are missing important functionality without this, and/or a workaround is difficult

         3. Major: a small minority of users are missing important functionality without this, and there is a workaround

         4. Minor: a niche use case is missing some support, but it does not affect usage or is easily worked around

         5. Trivial: a nice-to-have change but unlikely to be any problem in practice otherwise
            

      3. Component
      4. Affects Version. For Bugs, assign at least one version that is known to exhibit the problem or need the change.
   4. To avoid conflicts, assign the JIRA ticket to yourself if you plan to work on it. Leave it unassigned otherwise.
      
4. If the change is a large change, consider inviting discussion on the issue at dev@bookkeeper.apache.org first before proceeding to implement the change.
   

Review Board Workflow

1. Create local branch from master.

   $ git checkout -b BOOKKEEPER-XXXX

   
   

2. Make your modifications, add tests and run the whole test suite.
3. Commit your changes.
   

4. Generate a patch.

   $ git format-patch --no-prefix master

   
   

5. Upload the patch to JIRA.
6. If the patch is non-trivial, also upload it to review board under bookkeeper-git.
7. Click on Patch Available in JIRA to signal that the patch is ready to be reviewed.
8. The jenkin build will build the patch and run various checks like long lines, trailing spaces, findbugs. The pre-commit build report will be posted as a comment to the ticket. Please watch the comment and address the failures observed in pre-commit job and iterator over them.
   

Git Workflow

Pull Request

The Review Process

Closing Your Pull Request / JIRA

(WIP)