X-Mailer: ASF-Git Admin Mailer Subject: [44/50] [abbrv] accumulo-website git commit: Jekyll build from gh-pages:a71ede8 archived-at: Tue, 22 Nov 2016 19:41:06 -0000 http://git-wip-us.apache.org/repos/asf/accumulo-website/blob/59a6d65d/contributor/contrib-projects.html ---------------------------------------------------------------------- diff --git a/contributor/contrib-projects.html b/contributor/contrib-projects.html new file mode 100644 index 0000000..08f9aac --- /dev/null +++ b/contributor/contrib-projects.html @@ -0,0 +1,230 @@ + + + + + + + + + + + + +Contrib Projects + + + + + + + + + + + + +

+ + +

+ +

Contrib Projects

+ +

Apache Accumulo is a complex distributed system. In order to minimize that +complexity for both operators and developers the project maintains contrib +repositories for instructive applications and code that builds interoperability +between Accumulo and other systems. This helps minimize the set of dependencies +needed when building or installing Accumulo, keeps the build time down, and +allows the contrib projects to follow their own release schedule.

+ +

Existing Contrib Projects

+ +

Each of the below contrib project handles their own development and release +cycle. For information on what version(s) of Accumulo they work with, see the +documentation for the individual project.

+ +

Instamo Archetype

+ +

A Maven Archetype that automates the customization of Instamo to quickly spin +up an Accumulo process in memory.

+ +

The Apache Accumulo Instamo Archetype uses Git version control +(browse|checkout). It builds with Apache +Maven. See the section Contributing to Contrib for +instructions on submitting issues and patches.

+ +

Wikisearch Application

+ +

A complex application example that makes use of most of the Accumulo feature +stack. The Wikisearch application provides an example of indexing and querying +Wikipedia data within Accumulo. It is a great place to start if you want to get +familiar with good development practices building on Accumulo.

+ +

For details on setting up the application, see the project's README. You can +also read an overview and some performance numbers.

+ +

The Apache Accumulo Wikisearch Example uses Git version control +(browse|checkout). It builds with +Apache Maven. See the section Contributing to Contrib for +instructions on submitting issues and patches.

+ +

Hama Integration

+ +

An implementation for running Bulk Synchronous Parallel (BSP) +algorithms implemented via Apache Hama on top of data stored +in Accumulo.

+ +

The Apache Accumulo BSP implementation uses Git version control +(browse|checkout). It builds with Apache +Maven. See the section Contributing to Contrib for +instructions on submitting issues and patches.

+ +

Contributing to Contrib

+ +

All contributions to the various Apache Accumulo contrib projects should follow +the same process used in the primary project. All contributions +should have a corresponding issue filed in the contrib component in the +Accumulo issue tracker.

+ +

Adding a new Contrib Project

+ +

Proposals for new contrib projects should be sent to the Accumulo mailing +list for developers.

+ +

If an example application only makes use of a single Accumulo feature, it is +probably better off as an Accumulo version-specific example. You can see +several of these demonstrative applications in the simple example +codebase and the related published documentation for versions +1.7 and 1.6.

+ + +

+ + + + + +

+ + http://git-wip-us.apache.org/repos/asf/accumulo-website/blob/59a6d65d/contributor/git.html ---------------------------------------------------------------------- diff --git a/contributor/git.html b/contributor/git.html new file mode 100644 index 0000000..bb8dd45 --- /dev/null +++ b/contributor/git.html @@ -0,0 +1,686 @@ + + + + + + + + + + + + +Git + + + + + + + + + + + + +

+ + +

+ +

Git

+ +

Git is an open source, distributed version control system +which has become very popular in large, complicated software projects due to +its efficient handling of multiple, simultaneously and independently developed +branches of source code.\

+ +

Workflow Background

+ +

Likely the most contested subject matter regarding switching an active team +from one SCM tool to another is a shift in the development paradigm.

+ +

Some background, the common case, as is present with this team, is that +developers coming from a Subversion history are very light on merging being a +critical consideration on how to perform development. Because merging in +Subversion is typically of no consequence to the complete view of history, not +to mention that Subversion allows “merging” of specific revisions instead of +sub-trees. As such, a transition to Git typically requires a shift in mindset +in which a fix is not arbitrarily applied to trunk (whatever the main +development is called), but the fix should be applied to the earliest, non +end-of-life (EOL) version of the application.

+ +

For example, say there is a hypothetical application which has just released +version-3 of their software and have shifted their development to a version-4 +WIP. Version-2 is still supported, while version-1 was just EOL’ed. Each +version still has a branch. A bug was just found which affects all released +versions of this application. In Subversion, considering the history in the +repository, it is of no consequence where the change is initially applied, +because a Subversion merge is capable of merging it to any other version. +History does not suffer because Subversion doesn’t have the capacities to +accurately track the change across multiple branches. In Git, to maintain a +non-duplicative history, it is imperative that the developer choose the correct +branch to fix the bug in. In this case, since version-1 is EOL’ed, version-2, +version-3 and the WIP version-4 are candidates. The earliest version is +obviously version-2; so, the change should be applied in version-2, merged to +version-3 and then the version-4 WIP.

+ +

The importance of this example is making a best-attempt to preserve history +when using Git. While Git does have commands like cherry-pick which allow the +contents of a commit to be applied from one branch to another which are not +candidates to merge without conflict (which is typically the case when merging +a higher version into a lower version), this results in a duplication of that +commit in history when the two trees are eventually merged together. While Git +is smart enough to not attempt to re-apply the changes, history still contains +the blemish.

+ +

The purpose of this extravagant example is to outline, in the trivial case, how +the workflow decided upon for development is very important and has direct +impact on the efficacy of the advanced commands bundled with Git.

+ +

Proposed Workflow

+ +

This is a summary of what has been agreed upon by vocal committers/PMC members +on dev@accumulo.apache.org. Enumeration of +every possible situation out of the scope of this document. This document +intends to lay the ground work to define the correct course of action regardless +of circumstances. Some concrete examples will be provided to ensure the +explanation is clear.

+ +

+
Active development is performed concurrently over no less than two versions +of Apache Accumulo at any one point in time. As such, the workflow must +provide guidance on how and where changes should be made which apply to +multiple versions and how to ensure that such changes are contained in all +applicable versions.
+
+
Releases are considered extremely onerous and time-consuming so no emphasis +is placed on rapid iterations or development-cycles.
+
+
New features typically have lengthy development cycles in which more than +one developer contributes to the creation of the new feature from planning, +to implementation, to scale testing. Mechanisms/guidance should be provided +for multiple developers to teach contribute to a remote-shared resource.
+
+
The repository should be the irrefutable, sole source of information +regarding the development of Apache Accumulo, and, as such, should have +best-efforts given in creating a clean, readable history without any single +entity having to control all write access and changes (a proxy). In other +words, the developers are the ones responsible for ensuring that previous +releases are preserved to meet ASF policy, for not rewriting any public +history of code not yet officially released (also ASF policy relevant) and +for a best-effort to be given to avoid duplicative commits appearing in + history created by the application of multiple revisions which have + different identifying attributes but the same contents (git-rebase and + git-cherry-pick).
+

+ +

The implementation

+ +

Contributors

+ +

Use the following steps, original derived from Apache Kafka’s simple +contributor +workflow.

+ +

To be specific, let’s consider a contributor wanting to work on a fix for the +Jira issue ACCUMULO-12345 that affects 1.5.0 release.

+ +

+
Ensure you configured Git with your information
+ +
git config --global user.name 'My Name' && git config --global user.email + 'myname@mydomain.com'
+
+
Clone the Accumulo repository:
+ +
git clone https://git-wip-us.apache.org/repos/asf/accumulo.git accumulo
+
+
or update your local copy:
+ +
git fetch && git fetch --tags
+
+
For the given issue you intend to work on, choose the ‘lowest’ fixVersion +and create a branch for yourself to work in. This example is against the next release of 1.5
+ +
git checkout -b ACCUMULO-12345-my-work origin/1.5
+
+
Make commits as you see fit as you fix the issue, referencing the issue name +in the commit message:
+ +
git commit -av
+ +
Please include the ticket number at the beginning of the log message, and + in the first line, as it’s easier to parse quickly. For example:
+ +
ACCUMULO-2428 throw exception when rename fails after compaction
+ +
Consider following the git log message format described in + Zach Holman’s talk + (specifically slides 78-98, beginning at 15:20 into the video). Essentially, + leave a short descriptive message in the first line, skip a line, and write + more detailed stuff there, if you need to. For example:
+ +
ACCUMULO-2194 Add delay for randomwalk Security teardown
+ +
If two Security randomwalk tests run back-to-back, the second test may see that the + table user still exists even though it was removed when the first test was torn down. + This can happen if the user drop does not propagate through Zookeeper quickly enough. + This commit adds a delay to the end of the Security test to give ZK some time.
+
+
Assuming others are developing against the version you also are, as you +work, or before you create your patch, rebase your branch against the remote +to lift your changes to the top of your branch. The branch specified here should be the same one you used in step 4.
+ +
git pull --rebase origin 1.5
+
+
At this point, you can create a patch file from the upstream branch to +attach to the ACCUMULO-12345 Jira issue. The branch specified here should be teh same one you used in step 4.
+ +
git format-patch --stdout origin/1.5 > ACCUMULO-12345.patch
+

+ +

An alternative to creating a patch is submitting a request to pull your changes +from some repository, e.g. Github. Please include the repository and branch +name merge in the notice to the Jira issue, e.g.

+ +

repo=git://github.com/<username>/accumulo.git branch=ACCUMULO-12345
+

+ +

A second alternative is to use Github’s “Pull Requests” feature against the +Apache Accumulo account. Notifications of +new pull-requests from Github should automatically be sent to +dev@accumulo.apache.org.

+ +

Ignoring specifics, contributors should be sure to make their changes against +the earlier version in which the fix is intended, git-rebase‘ing their +changes against the upstream branch so as to keep their changes co-located and +free of unnecessary merges.

+ +

Developers

+ +

Primary Development

+ +

Primary development should take place in master which is to contain the most +recent, un-released version of Apache Accumulo. Branches exist for minor releases +for each previously released major version.

+ +

Using long-lived branches that track a major release line simplifies management and +release practices. Developers are encouraged to make branches for their own purposes, +for large features, release candidates or whatever else is deemed useful.

+ +

Reviewing contributor changes

+ +

It is always the responsibility of committers to determine that a patch is +intended and able to be contributed. From the +new committer’s guide: +“Please take care to ensure that patches are original works which have been +clearly contributed to the ASF in public. In the case of any doubt (or when a +contribution with a more complex history is presented) please consult your +project PMC before committing it.”

+ +

Extra diligence may be necessary when code is contributed via a pull request. +Committers should verify that the contributor intended to submit the code as a +Contribution under the Apache License. +When pulling the code, committers should also verify that the commits pulled match the +list of commits sent to the Accumulo dev list in the pull request.

+ +

Patches

+ +

Developers should use the following steps to apply patches from +contributors:

+ +

+
Checkout the branch for the major version which the patch is intended:
+ +
git checkout 1.5
+
+
Verify the changes introduced by the patch:
+ +
git apply --stat ACCUMULO-12345.patch
+
+
Verify that the patch applies cleanly:
+ +
git apply --check ACCUMULO-12345.patch
+
+
If all is well, apply the patch:
+ +
git am --signoff < ACCUMULO-12345.patch
+
+
When finished, push the changes:
+ +
git push origin 1.5
+
+
Merge where appropriate:
+ +
git checkout master && git merge 1.5
+

+ +

Github Pull-Requests

+ +

If the contributor submits a repository and branch to pull +from, the steps are even easier:

+ +

+
Add their repository as a remote to your repository
+ +
git remote add some_name ${repository}
+
+
Fetch the refs from the given repository
+ +
git fetch ${repository}
+
+
Merge in the given branch to your local branch
+ +
git merge some_name/${branch}
+
+
Delete the remote:
+ +
git remote remove some_name
+

+ +

If the branch doesn’t fast-forward merge, you likely want to inform the +contributor to update their branch to avoid the conflict resolution and merge +commit. See the Git +manual +for more information on merging. When merging a pull-request, it’s best to not +include a signoff on the commit(s) as it changes the final commit ID in the +Accumulo repository. This also has the negative of not automatically closing +the Pull-Request when the changes are made public.

+ +

Feature Branches

+ +

Ease in creating and using feature branches is a desirable merit which Git +provides with little work. Feature branches are a great way in which developers +to work on multiple, long-running features concurrently, without worry of +mixing code ready for public-review and code needing more internal work. +Additionally, this creates an easily consumable series of commits in which +other developers can track changes, and see how the feature itself evolved.

+ +

To prevent developers’ feature branches from colliding with one another, it was +suggested to impose a “hierarchy” in which shared feature branches are prefixed +with <apache_id>/ACCUMULO-<issue#>[-description].

+ +

+
Create a branch off of master.
+ +
git checkout <apache_id>/ACCUMULO-<issue#> master
+
+
Create the feature, commiting early and often to appropriately outline the +“story” behind the feature and it’s implementation.
+
+
As long as you have not collaborating with others, git-rebase your feature +branch against upstream changes in master
+ +
git fetch && git rebase origin/master
+
+
If you are actively collaborating with others, you should be nice and not +change their history. Use git-merge instead.
+ +
git fetch && git merge origin/master
+
+
Continue steps 2 through 4 until the feature is complete.
+
+
Depending on the nature, duration and history of the changes in your feature +branch, you can choose to:
+ +
- +
  ‘Simple’ Merge:
  + +
  git checkout master && git merge <apache_id>/ACCUMULO-<issue#>
  +
- +
  Rebase and merge – keeps all feature-branch commits +co-located:
  + +
  git fetch && git rebase origin/master && git checkout master && git merge <apache_id>/ACCUMULO-<issue#>
  +
- +
  Merge with squash – feature branch history is a mess, just make one commit +with the lump-sum of your feature branch changes:
  + +
  git checkout master && git merge --squash <apache_id>/ACCUMULO-<issue#>
  +
+

+ +

Changes which affect multiple versions (a.k.a. merging)

+ +

Merging can be a very confusing topic for users switching to Git, but it can be +summarized fairly easily.

+ +

+
Precondition: choose the right branch to start! (lowest, applicable version +for the change)
+
+
Get your changes fixed for that earliest version.
+
+
Switch to the next highest version which future minor versions will be +released (non-EOL major release series).
+
+
git-merge the branch from #1 into the current.
+
+
In the face of conflicts, use options from git-merge to help you.
+ +
- git checkout new-version && git merge --stat old-version
- git checkout new-version && git merge --no-commit old-version
+
+
Treat your current branch as the branch from #2, and repeat from #2.
+

+ +

When merging changes across major releases, there is always the possibility of +changes which are applicable/necessary in one release, but not in any future +releases, changes which are different in implementation due to API changes, or +any number of other cases. Whatever the actual case is, the developer who made +the first set of changes (you) is the one responsible for performing the merge +through the rest of the active versions. Even when the merge may results in a +zero-length change in content, this is incredibly important to record as you +are the one who knows that this zero-length change in content is correct!

+ +

Release Management

+ +

Releases, although not a day to day task, have their own unique steps which are +to be followed. Releases can be categorized in to minor and major releases.

+ +

A minor release

+ +

A minor release is some set of changes z' on top of a version x.y.z. +Typically, z' is simply z + 1, e.g. given a release named ‘1.6.0’, and the +next minor release is ‘1.6.1’. These changes for z' should not break any +client code which works against z and should absolutely not change the public +API.

+ +

By convention, the branch containing the changes z' should be named +x.y (where the changes for z' are commits since x.y.z. The steps to take are as follows:

+ +

Prepare the release candidate. Release +Guide, Maven +Instructions
Create a branch for the release candidate from the x.y branch, +named something like x.y.z'-RCN.
Test and Vote
Create a GPG-signed tag with the correct final name: x.y.z'
Push a delete of the remote branch x.y.z'-RCN

+ +

This process is not firm and should not be viewed as requirements for making a release. +The release manager is encouraged to make use branches/tags in whichever way is best.

+ +

A major release

+ +

A major release is a release in which multiple new features are introduced +and/or the public API are modified. The major release y', even when the +client API is not modified, will typically contain many new features and +functionality above the last release series y. A major release also resets +the z value back to 0.

+ +

The steps to create a new major release are very similar to a minor release:

+ +

Prepare the release candidate. reference release instructions
Create a tag of the release candidate from the x.y branch, +named something like x.y.0-RCN.
Test and Vote
Create a GPG-signed tag with the correct final name: x.y.0
Push a delete of the remote branch x.y.0-RCN

+ +

The infrastructure

+ +

This section deals with the changes that must be requested through INFRA. As +with any substantial INFRA request, the VOTE and result from the mailing should +be referenced so INFRA knows that the request has been acknowledged. Likely, a +PMC member should be the one to submit the request.

+ +

Repositories

+ +

I believe that we will need multiple repositories to best align ourselves with +how we currently track “Accumulo” projects. The repositories follow:

+ +

+
The main source tree. This will track the standard trunk, branches, tags +structure from Subversion for Apache Accumulo.
+
+
One repository for every project in +contrib: Accumulo-BSP, +Instamo Archetype, and the Wikisearch project. Each of these +are considered disjoint from one another, and the main source tree, so they +each deserve their own repository.
+

+ +

Given the list of repositories that currently exist on the ASF +site and a brief search over INFRA +tickets, multiple repositories for a single Apache project is not an issue. +Having this list when making the initial ticket will likely reduce the amount +of work necessary in opening multiple INFRA tickets.

+ +

Mirroring

+ +

It should be noted in the INFRA requst that each repository will also need to +be configured to properly mirror to the ASF Github +account to provide the same functionality with current have via the git+svn +mirror. This should be noted in the INFRA request. Same change needs to be +applied for the Apache hosted mirror’ing.

+ +

Mailing lists

+ +

It should be noted in the INFRA request that commit messages should be sent to +commits@accumulo.apache.org. The subject +can be decided on using the provided +variables.

+ +

Examples

+ +

For the sake of clarity, some examples of common situations are included below.

+ +

Releasing 1.6.0

+ +

+
Branch from master to 1.6
+ +
git checkout master && git branch 1.6
+
+
Tag 1.6.0-RC1 from the just created 1.6 branch
+ +
git tag 1.6.0-RC1 1.6
+
+
Test, vote, etc. and tag from 1.6.0-RC1
+ +
git -s tag 1.6.0 1.6.0-RC1
+
+
Delete the RC tag, if desired.
+ +
git tag -d 1.6.0-RC1 && git push --delete origin 1.6.0-RC1
+
+
Ensure master contains all features and fixes from 1.6.0
+ +
git checkout master && git merge 1.6
+
+
Update the project version in master to 1.7.0-SNAPSHOT
+

+ + +

+ + + + + +

+ + http://git-wip-us.apache.org/repos/asf/accumulo-website/blob/59a6d65d/contributor/index.html ---------------------------------------------------------------------- diff --git a/contributor/index.html b/contributor/index.html new file mode 100644 index 0000000..a8dd20b --- /dev/null +++ b/contributor/index.html @@ -0,0 +1,185 @@ + + + + + + + + + + + + +Contributor Guide + + + + + + + + + + + + +

+ + +

+ +

Contributor Guide

+ +

This page contains resources and documentation for Accumulo contributors.

+ +

Any documentation that is helpful to Accumulo users should be placed in the user manual.

+ +

JIRA - Accumulo’s Issue Tracker
GitHub - Pull requests can be made on GitHub
Jenkins & TravisCI - Accumulo build servers
Source Guide
Git Workflow
Versioning
Contrib Projects
Review Board

+ +

Below are resources for Accumulo committers which may also be helpful to contributors.

+ +

Making Releases
Verifying Releases

+ + +

+ + + + + +

+ + http://git-wip-us.apache.org/repos/asf/accumulo-website/blob/59a6d65d/contributor/rb.html ---------------------------------------------------------------------- diff --git a/contributor/rb.html b/contributor/rb.html new file mode 100644 index 0000000..855f311 --- /dev/null +++ b/contributor/rb.html @@ -0,0 +1,267 @@ + + + + + + + + + + + + +Using Review Board + + + + + + + + + + + + +

+ + +

+ +

Using Review Board

+ +

The Apache Software Foundation provides an instance of +Review Board (RB) for projects to use in code reviews. Here is how RB can +be used to support development in the context of the +Apache Accumulo bylaws.

+ +

Contributors to Accumulo are encouraged to use RB for non-trivial patches and +any time feedback is desired. No one is required to use RB, but its ready +availability and better interface for feedback can help with reviews. Committers +seeking review prior to pushing changes can also benefit similarly.

+ +

Roles for Review Board

+ +

Optional Pre-Commit Review

+ +

Accumulo operates under the Commit-Then-Review (CtR) policy, so code +review does not need to occur prior to commit. However, a committer may opt to +hold a code review before commit for changes that, in their opinion, would +benefit from additional attention. RB can be used to conduct such code reviews.

+ +

Consensus Approval after a Code Change Veto

+ +

Code changes are approved by lazy approval, with consensus approval following +a veto (see the Actions section of the bylaws). RB can be used +to coordinate a consensus approval vote by providing a convenient view of the +code change under consideration. The vote itself must still be held on the +developer mailing list.

+ +

Guidelines for Posting a Review

+ +

It is best to post a git-generated patch as the basis for a review. RB does +not support patches containing multiple commits, so either squash commits +first, or submit a diff spanning the changeset. The rbt and post-review +tools generate diffs.
Strive to make your changes small. Reviewers are less likely to want to +trudge through a review with lots of changes, and are more likely to miss +problems.
Begin the summary of the review with a JIRA issue number. A review must +always be associated with a JIRA issue. The issue number should also be +entered in the “Bugs” field of the review, providing a link to JIRA.
The “Branch” field should contain the name of the branch that the code change +is based on (e.g., the base of your git feature branch).
Include the “accumulo” user group as reviewers. Also include specific people +as individual reviewers, even if they are in the “accumulo” group, if you +deem them of primary importance for the review (e.g., you have been working +out problems with the review with them, they are expert in the area).
Use the description to summarize the change under review. Include helpful +instructions to the reviewers here.
Describe any testing done on the change. It is not expected that reviewers +will do their own testing, and they may reject the review if you have not +done sufficient testing yourself.
Avoid submitting generated code for review if it can be reproduced by a +reviewer.

+ +

After the review is published, set the status of the associated JIRA issue to +“Patch Available” as a signal to reviewers. Also, link to the review from the +issue (More -> Link -> Web Link) to help viewers of the issue find the review +and assess its progress.

+ +

Guidelines for Reviewing Code

+ +

Try to associate comments with relevant lines of code in the review.
By default, each comment opens a review issue. If a comment pertains to +something that should not block the review from completing successfully, then +clear the “Open an issue” checkbox before saving your feedback. Examples that +might qualify as non-issues: minor formatting/whitespace issues, spelling +mistakes, general background questions.
If a review looks good, be sure to “Ship It” by either using the “Ship It!” +button or by submitting a general review with the “Ship It” checkbox checked.

+ +

Guidelines for Completing a Review

+ +

These guidelines do not apply to consensus approval votes, since the vote +completion depends on the votes registered in the developer mailing list.

+ +

Use your judgement for the number of “Ship It”s you want to receive to +consider a review passed. Usually, getting one “Ship It” is enough to proceed +with a commit. It is recommended that the “Ship It” be from a committer who +is a neutral party not involved in the change under review.
Use your judgement for the minimum time length you set for the review. Simple +changes can be up for just a day, while complex ones should take up to seven.
Review time should be extended in the face of problems discovered in the +review. Update the review with improved code instead of discarding (i.e., +closing unsuccessfully) it and beginning a new one.
A review should not be “submitted” (i.e., closed successfully) unless there +are no outstanding issues. Check with reviewers to ensure that their issues +are resolved satisfactorily.
A review should be “discarded” if the code requires major rework or it +becomes obvious it should never be committed (due to design changes, +becoming overcome by events, being back-burnered, etc.).
Don’t leave a review open indefinitely. Once you have received sufficient +feedback to submit or discard it, do so. If there has been no activity for +some time, discard the review. A new one can always be created later.

+ +

Once you’ve closed a review as submitted, if you are unable to commit your +changes yourself, attach the final version of them to the relevant JIRA issue. +They should be in the form of a patch containing a single commit, +per the final steps of the contribution process.

+ + +

+ + + + + +

+ + http://git-wip-us.apache.org/repos/asf/accumulo-website/blob/59a6d65d/contributor/releasing.html ---------------------------------------------------------------------- diff --git a/contributor/releasing.html b/contributor/releasing.html new file mode 100644 index 0000000..9eec7f2 --- /dev/null +++ b/contributor/releasing.html @@ -0,0 +1,303 @@ + + + + + + + + + + + + +Making a Release + + + + + + + + + + + + +

+ + +

+ +

Making a Release

+ +

This is a guide for the creation of a release of Apache Accumulo.

+ +

Setup

+ +

There are number of things that are required before attempting to build a release.

+ +

Use gpg-agent, and be sure to increase the gpg-agent cache timeout (via .gnupg/gpg-agent.conf) to ensure that the agent doesn’t require re-authentication mid-build, as it will cause things to fail. For example, you can add default-cache-ttl 6000 to increase the timeout from the default of 10 minutes to over an hour. If you do not have a GPG key, reference the very thorough ASF release signing documentation.
Ensure that you’re using the correct major release of Java (check javadoc too).
Ensure that you’re building Apache Accumulo with a username that has the same name as your Apache ID (this is due to +the maven-release-plugin and staging the release candidate).
Update the CHANGES file so that it’s in sync with Jira (manual process).
Ensure that you have a texlive distribution installed so you are able to build the documentation.
Have a clean workspace before starting.

+ +

Given all of this, it’s recommended that you only attempt making a release from a GNU/Linux machine.

+ +

Create the candidate

+ +

TL;DR

+ +

./assemble/build.sh --create-release-candidate to make the release candidate
git tag $version $version-rcN to create an RC tag from the actual tag
git tag -d $version make sure you don’t accidentally push a “release” tag
git push origin $version-rcN push the RC tag
git checkout -b $version-rcN-branch save off the branch from the Maven release plugin
VOTE
If vote fails, fix the original branch and start over.
If vote passes, git merge $version-rcN-branch back into the original branch you released from.
git tag -s $version-rcN $version make a GPG-signed tag
git push origin $version push the signed tag.

+ +

Long-winded explanation

+ +

You should use the provided script assemble/build.sh to create the release candidate. This script is +desirable as it activates all necessary maven profiles in addition to verifying that certain preconditions +are met, like RPM signing availablilty and the ability to sign files using GPG. The –test option can +be used as a dry run for creating a release candidate. The –create-release-candidate option should be +used to create the actual release candidate.

+ +

When invoking build.sh with the –create-release-candidate option, the majority of the work will be performed +by the maven-release-plugin, invoking release:clean, release:prepare, and release:perform. These will +guide you through choosing the correct versions. The default options provided should be what you choose. +It is highly recommended that an ‘RC’ suffix is not appended to the release version the plugin prompts +you for, as that will result in that version string being placed into the poms, which then would require +voting to occur on artifacts that cannot be directly promoted. After the build.sh script finishes (this will +likely take at least 15 minutes, even on recent hardware), your current branch will be on the “next” version +that you provided to the release plugin.

+ +

One unwanted side-effect of this approach is that after creating this branch, but before invoking release:perform, +you must edit the release.properties to add the -rcN suffix to the value of scm.tag. Otherwise, the release +plugin will complain that it cannot find the branch for the release. With a successful invocation of mvn release:perform, +a staging repository will be made for you on the ASF Nexus server which you can log into with your ASF +credentials.

+ +

After you log into Nexus, click on Staging Repositories in the Build Promotion toolbar on the left side of +the screen. Assuming your build went according to plan, you should have a new staging repository made for +you. At this point, you should inspect the artifacts that were staged to ensure that they are as you expect +them to be. When you’re ready to present those artifacts for voting, you need to close that repository which +will make it publicly available for other members to inspect.

+ +

Vote

+ +

At this point, you should have a closed repository that’s ready to vote on. Send a message to the dev +list and get the ball rolling. If the vote ultimately fails, you delete +the staged repository, clean up the branch you created (or wait until the release ultimately passes if you +choose), and fix what needs fixing.

+ +

If the vote passes, huzzah, you’re almost done.

+ +

Promote the artifacts

+ +

Promote that staged repository using Nexus which you can do with the click of a button. This will trigger +a process to get the release out to all of the mirrors.

+ +

Create the final Git tag

+ +

The Git repository should also contain a tag which refers to the final commit which made up a release. This tag +should also be signed with your GPG key. To ensure proper retention on release (stemming from ASF policy +requirements), This final tag must being with “rel/”. For example, a release of 1.7.0 should have a corresponding +tag name of “rel/1.7.0”.

+ +

Copy artifacts to dist.apache.org

+ +

An SVN server is running at https://dist.apache.org/repos/dist/release/accumulo. You need to upload the release +tarballs, the GPG signatures and checksum files to the correct directory (based on the release number). If you +are releasing a bug-fix release, be sure to delete the previous release in the same line (e.g. if you release +1.6.2, remove 1.6.1). The old tarballs removed from dist.apache.org will still be preserved in archive.apache.org +automatically.

+ +

Update projects.apache.org

+ +

Fill out the add release form to update the projects website.

+ +

Update the Website

+ +

After a successful vote, this website needs to be updated with the new artifacts.

+ +

Copy Accumulo User Manual (HTML version exists in >=1.7.0)
Update downloads page
Create release notes (ensure notes contain link to JIRA changes for that version)
Remove previous bug-fix release (if applicable)
Update examples README files
Update doap_Accumulo.rdf

+ +

Javadocs

+ +

Javadocs are easy to update. Using the latest JDK7 or later (at least JDK 7u21 +to avoid known vulnerabilities), follow these steps:

+ +

Unpack the source release tarball and change to its root directory, or checkout the SCM tag for the release
Build the javadocs with mvn clean package javadoc:aggregate -DskipTests -Paggregate-javadocs
Take note that the javadocs you will need to copy are the entire contents of ./target/site/apidocs/
Checkout the gh-pages branch (you may need to move the contents of ./target/site/apidocs outside your git workspace to switch branches)
Remove any existing apidocs from the appropriate version folder (e.g. 1.6/apidocs for a 1.6.x release)
Copy the entire contents of the new apidocs directory (identified in step 3) to the destination (e.g. to 1.6/apidocs)
Continue updating the site content, as needed
Commit the changes
Update the site using jekyll with ./_devtools/git-hooks/post-commit (if you don’t have the commit hook already configured)
Don’t forget to push both the gh-pages and asf-site branches
Verify that javadocs have been updated on the production site (e.g. https://accumulo.apache.org/1.6/apidocs/)

+ +

References

+ +

Some good references that explain a few things:

+ +

+ + +

+ + + + + +

+ +