Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id AED69200D3A for ; Wed, 15 Nov 2017 16:47:17 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id ACB5C160BF6; Wed, 15 Nov 2017 15:47:17 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 52901160BEA for ; Wed, 15 Nov 2017 16:47:15 +0100 (CET) Received: (qmail 27179 invoked by uid 500); 15 Nov 2017 15:47:14 -0000 Mailing-List: contact commits-help@accumulo.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@accumulo.apache.org Delivered-To: mailing list commits@accumulo.apache.org Received: (qmail 27170 invoked by uid 99); 15 Nov 2017 15:47:14 -0000 Received: from ec2-52-202-80-70.compute-1.amazonaws.com (HELO gitbox.apache.org) (52.202.80.70) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 15 Nov 2017 15:47:14 +0000 Received: by gitbox.apache.org (ASF Mail Server at gitbox.apache.org, from userid 33) id B2C6781B49; Wed, 15 Nov 2017 15:47:13 +0000 (UTC) Date: Wed, 15 Nov 2017 15:47:13 +0000 To: "commits@accumulo.apache.org" Subject: [accumulo-website] branch master updated: ACCUMULO-4714 Improved contributing docs for new developers (#37) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Message-ID: <151076083365.20222.9277071413017649908@gitbox.apache.org> From: mwalch@apache.org X-Git-Host: gitbox.apache.org X-Git-Repo: accumulo-website X-Git-Refname: refs/heads/master X-Git-Reftype: branch X-Git-Oldrev: bdcf5d2b12f883985936d8b27833313b2b8ab4e7 X-Git-Newrev: 73cbdd9e6a3734f0263a9df0be9e07848f1bd7d7 X-Git-Rev: 73cbdd9e6a3734f0263a9df0be9e07848f1bd7d7 X-Git-NotificationType: ref_changed_plus_diff X-Git-Multimail-Version: 1.5.dev Auto-Submitted: auto-generated archived-at: Wed, 15 Nov 2017 15:47:17 -0000 This is an automated email from the ASF dual-hosted git repository. mwalch pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/accumulo-website.git The following commit(s) were added to refs/heads/master by this push: new 73cbdd9 ACCUMULO-4714 Improved contributing docs for new developers (#37) 73cbdd9 is described below commit 73cbdd9e6a3734f0263a9df0be9e07848f1bd7d7 Author: Mark Owens AuthorDate: Wed Nov 15 10:47:11 2017 -0500 ACCUMULO-4714 Improved contributing docs for new developers (#37) * Merged get_involved.md & mailing_list.md pages into contact-us.md * Created short guide (how-to-contribute.md) & long guide (contributors-guide.md) * Created quickstart page for Accumulo 1.x * Created CONTRIBUTING.md for website --- CONTRIBUTING.md | 32 ++ _includes/nav.html | 6 +- contributor/contributors-guide.md | 649 +++++++++++++++++++++++++++++++ contributor/git.md | 451 --------------------- contributor/index.md | 49 --- contributor/rb.md | 4 +- contributor/release-management.md | 119 ++++++ contributor/source.md | 193 --------- contributor/verifying-release.md | 4 +- css/accumulo.scss | 2 +- pages/{mailing_list.md => contact-us.md} | 45 ++- pages/get_involved.md | 96 ----- pages/how-to-contribute.md | 150 +++++++ pages/quickstart-1.x.md | 104 +++++ 14 files changed, 1102 insertions(+), 802 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..675198c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,32 @@ + + +# Contributing to the Accumulo Website + +Contributions to the website can be made by creating pull requests to this repo on GitHub. + +Before creating a pull request, follow the instructions in the [README.md] to test +your changes by running the website locally. + +If you cannot run the website locally, it's OK to submit your pull request. A committer +will test your changes before merging. + +For general information on contributing to Accumulo projects, check out the +[How To Contribute][contribute] page. + +[README.md]: README.md +[contribute]: https://accumulo.apache.org/how-to-contribute/ diff --git a/_includes/nav.html b/_includes/nav.html index 295d2e6..f7891cf 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -24,6 +24,7 @@
  • Documentation diff --git a/contributor/contributors-guide.md b/contributor/contributors-guide.md new file mode 100644 index 0000000..d42ac8e --- /dev/null +++ b/contributor/contributors-guide.md @@ -0,0 +1,649 @@ +--- +title: Contributor Guide +permalink: /contributors-guide/ +--- + +This page contains resources and documentation of interest to current and potential contributors to the Accumulo project. Any documentation that is helpful to Accumulo users should go in the [Accumulo User Manual][manual]. + +If your are interested in quickly getting an Accumulo instance up and running, see the Accumulo Quickstart guides [(1.x)][quickstart1x]/[(2.x)][quickstart2x] or refer to the [Uno] project on Github. + +- [How to contribute to Apache Accumulo][1] +- [Project Resources][2] + - [GitHub][3] + - [JIRA][4] + - [Jenkins/TravisCI][5] +- [Create a Ticket for Bugs or New Features][6] +- [Building Accumulo from Source][7] + - [Installing Apache Thrift][29] + - [Checking out from Git][8] + - [Running a Build][9] +- [Providing a contribution][10] + - [Proposed Workflow][11] + - [The Implementation][12] + - [Contributors][13] + - [Developers][14] + - [Primary Development][15] + - [Reviewing Contributor Changes][16] + - [Submit Contribution via Patch][17] + - [Submit Contribution via Pull Request][18] + - [Feature Branches][19] + - [Changes Which Affect Multiple-Versions (a.k.a Merging)][20] +- [Code Review Process][21] +- [Additional Contributor Information][22] + - [Coding Practices][25] + - [Merging Practices][23] + - [Project Examples][26] + - [Website Contributions][27] + - [Public API][24] + - [Contrib Projects][28] +- [Committer Documentation][32] +- [Project Governance][33] + + +## How to Contribute to Apache Accumulo + +Apache Accumulo welcomes contributions from the community. This is especially true of new contributors! You don’t need to be a software developer to contribute to Apache Accumulo. So, if you want to get involved in Apache Accumulo, there is almost certainly a role for you. View our [How to Contribute](/how-to-contribute/) page for additional details on the many opportunities available. + +## Project Resources + +Accumulo makes use of the following external tools for development. + +### GitHub + +Apache Accumulo® source code is maintained using [Git] version control and mirrored to [GitHub][github]. Source files can be browsed [here][browse] or at the [GitHub mirror][mirror]. + +The project code can be checked-out [here][mirror]. It builds with [Apache Maven][maven]. + +### JIRA + +Accumulo [tracks issues][jiraloc] with [JIRA][jira]. Prospective code contributors can view [open issues labeled for "newbies"][newbies] to search for starter tickets. Note that every commit should reference a JIRA ticket of the form ACCUMULO-#. + +### Jenkins/TravisCI + +Accumulo uses [Jenkins][jenkins] and [TravisCI](https://travis-ci.org/apache/accumulo) for automatic builds and continuous integration. + + [Master][masterbuild] + + [1.8 Branch][18build] + + [1.7 Branch][17build] + +## Create a Ticket for New Bugs or Feature + +If you run into a bug or think there is something that would benefit the project, we encourage you to file an issue at the [Apache Accumulo JIRA][jiraloc] page. Regardless of whether you have the time to provide the fix or implementation yourself, this will be helpful to the project. + +## Building Accumulo from Source + +### Installing Apache Thrift + +If you activate the 'thrift' Maven profile, the build of some modules will attempt to run the Apache Thrift command line to regenerate +stubs. If you activate this profile and don't have Apache Thrift installed and in your path, you will see a warning and +your build will fail. For Accumulo 1.5.0 and greater, install Thrift 0.9 and make sure that the 'thrift' command is in your path. +Watch out for THRIFT-1367; you may need to configure Thrift with --without-ruby. Most developers do not +need to install or modify the Thrift definitions as a part of developing against Apache Accumulo. + +### Checking out from Git + +There are several methods for obtaining the Accumulo source code. If you prefer to use SSH rather than HTTPS you can refer to the [GitHub help pages][github-help] for help in creating a GitHub account and setting up [SSH keys][ssh]. + +#### - from your Github Fork + +It is also possible to [fork][forking] a repository in GitHub so that you can freely experiment with changes without affecting the original project. You can then submit a [pull request](https://help.github.com/articles/about-pull-requests/) from your personal fork to the project repository when you wish to supply a contribution. + + git clone git@github.com:/accumulo.git + +##### Retrieval of upstream changes + +Additionally, it is beneficial to add a git remote for the mirror to allow the retrieval of upstream changes. + + git remote add upstream http://github.com/apache/accumulo.git + +#### - from the Github Mirror + + git clone https://github.com/apache/accumulo.git + +#### - from the Apache Hosted Repository + + git clone https://gitbox.apache.org/repos/asf/accumulo.git + +## Running a Build + +Accumulo uses [Apache Maven][maven] to handle source building, testing, and packaging. To build Accumulo, you will need to use Maven version 3.0.5 or later. + +You should familiarize yourself with the [Maven Build Lifecycle][lifecycle], as well as the various plugins we use in our [POM][pom], in order to understand how Maven works and how to use the various build options while building Accumulo. + +To build from source (for example, to deploy): + + mvn package -Passemble + +This will create a file `accumulo-*-SNAPSHOT-dist.tar.gz` in the assemble/target directory. Optionally, append `-DskipTests` if you want to skip the build tests. + +To build your branch before submitting a pull request, you'll probably want to run some basic "sunny-day" integration tests to ensure you haven't made any grave errors, as well as `checkstyle` and `findbugs`: + + mvn verify -Psunny + +To run specific unit tests, you can run: + + mvn package -Dtest=MyTest -DfailIfNoTests=false + +Or to run the specific integration tests MyIT and YourIT (and skip all unit tests), you can run: + + mvn verify -Dtest=NoSuchTestExists -Dit.test=MyIT,YourIT -DfailIfNoTests=false + +There are plenty of other options. For example, you can skip findbugs with `mvn verify -Dfindbugs.skip` or checkstyle `-Dcheckstyle.skip`, or control the number of forks to use while executing tests, `-DforkCount=4`, etc. You should check with specific plugins to see which command-line options are available to control their behavior. Note that not all options will result in a stable build, and options may change over time. + +If you regularly switch between major development branches, you may receive errors about improperly licensed files from the [RAT plugin][rat]. This is caused by modules that exist in one branch and not the other leaving Maven build files that the RAT plugin no longer understands how to ignore. + +The easiest fix is to ensure all of your current changes are stored in git and then cleaning your workspace. + + $> git add path/to/file/that/has/changed + $> git add path/to/other/file + $> git clean -df + +Note that this git clean command will delete any files unknown to git in a way that is irreversible. You should check that no important files will be included by first looking at the "untracked files" section in a ```git status``` command. + + $> git status + # On branch master + nothing to commit (working directory clean) + $> mvn package + { maven output elided } + $> git checkout 1.6.1-SNAPSHOT + Switched to branch '1.6.1-SNAPSHOT' + $> git status + # On branch 1.6.1-SNAPSHOT + # Untracked files: + # (use "git add ..." to include in what will be committed) + # + # mapreduce/ + # shell/ + nothing added to commit but untracked files present (use "git add" to track) + $> git clean -df + Removing mapreduce/ + Removing shell/ + $> git status + # On branch 1.6.1-SNAPSHOT + nothing to commit (working directory clean) + +## Providing a Contribution + +The Accumulo source is hosted at [https://gitbox.apache.org/][repo] . + +Like all Apache projects, a mirror of the git repository is also located on GitHub at [https://github.com/apache/accumulo][GitHub] which provides ease in [forking] and generating [pull requests (PRs)][pulls]. + +### 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 + +The most likely 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][dev-mail]. 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. + +1. 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. + +2. Releases are considered extremely onerous and time-consuming so no emphasis + is placed on rapid iterations or development-cycles. + +3. 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. + +4. 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 + +The following steps, originally derived from Apache kafka's +[simple contributor workflow][kafka], will demonstrate the gitflow implementation. + +### Contributors + +To be specific, let's consider a contributor wanting to work on a fix for the +Jira issue ACCUMULO-12345 that affects the 1.8 release. + +1. Ensure you configured Git with your information + + `git config --global user.name 'My Name' && git config --global user.email + 'myname@mydomain.com'` + +2. Clone the Accumulo repository: + + `git clone https://gitbox.apache.org/repos/asf/accumulo.git accumulo` + +3. or update your local copy: + + `git fetch && git fetch --tags` + +4. 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.8 + + `git checkout -b ACCUMULO-12345-my-work origin/1.8` + +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](https://zachholman.com/talk/more-git-and-github-secrets/) + (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. +``` + +6. 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.8` + +7. 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 the same one you used in step 4. + + `git format-patch --stdout origin/1.8 > 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//accumulo.git branch=ACCUMULO-12345 + +A second alternative is to use Github's "Pull Requests" feature against the +[Apache Accumulo account](https://github.com/apache/accumulo). Notifications of +new pull-requests from Github should automatically be sent to +[dev@accumulo.apache.org][dev-mail]. + +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](https://www.apache.org/dev/new-committers-guide#cla): +"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](https://www.apache.org/licenses/LICENSE-2.0.txt). +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. + +#### Submit Contribution via Patch + +Developers should use the following steps to apply patches from +contributors: + +1. Checkout the branch for the major version which the patch is intended: + + `git checkout 1.8` + +2. Verify the changes introduced by the patch: + + `git apply --stat ACCUMULO-12345.patch` + +3. Verify that the patch applies cleanly: + + `git apply --check ACCUMULO-12345.patch` + +4. If all is well, apply the patch: + + `git am --signoff < ACCUMULO-12345.patch` + +5. When finished, push the changes: + + `git push origin 1.8` + +6. Merge where appropriate: + + `git checkout master && git merge 1.8` + +#### Submit Contribution via Pull-Request + +If the contributor submits a repository and branch to pull +from, the steps are even easier: + +1. Add their repository as a remote to your repository + + `git remote add some_name ${repository}` + +2. Fetch the refs from the given repository + + `git fetch ${repository}` + +3. Merge in the given branch to your local branch + + `git merge some_name/${branch}` + +4. 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](https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging) +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 effect 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 `/ACCUMULO-[-description]`. + +1. Create a branch off of `master`. + + `git checkout /ACCUMULO- master` + +2. Create the feature, committing early and often to appropriately outline the +"story" behind the feature and it's implementation. + +3. 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` + +4. 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` + +5. Continue steps 2 through 4 until the feature is complete. + +6. 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 /ACCUMULO-` + + * **Rebase and merge** -- keeps all feature-branch commits + co-located: + + `git fetch && git rebase origin/master && git checkout master && git merge /ACCUMULO-` + + * **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 /ACCUMULO-` + +#### 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. + +0. **Precondition**: choose the right branch to start! (lowest, applicable version + for the change) + +1. Get your changes fixed for that earliest version. + +2. Switch to the next highest version which future minor versions will be + released (non-EOL major release series). + +3. `git-merge` the branch from #1 into the current. + +4. 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` + +5. 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! + +## Code review process + +Accumulo primarily uses GitHub (via pull requests) for code reviews, but has access to an instance of [Review Board](https://reviews.apache.org/) as well if that is preferred. + +Accumulo operates under the [Commit-Then-Review](https://www.apache.org/foundation/glossary#CommitThenReview) (CtR) policy, so a code review does not need to occur prior to commit. However, a commiter has the option to hold a code review before a commit happens if, in their opinion, it would benefit from additional attention. Full details of the code review process for Accumulo is documented [here](./rb) + +### Review Board + +Use of [Review Board][rb] has slowly diminished and been gradually replaced by GitHub reviews over the past year or so. + +## Additional Contributor Information + +### Coding Practices + +{: .table} +| **License Header** | Always add the current ASF license header as described in [ASF Source Header][srcheaders]. | +| **Trailing Whitespaces** | Remove all trailing whitespaces. Eclipse users can use Source→Cleanup option to accomplish this. | +| **Indentation** | Use 2 space indents and never use tabs! | +| **Line Wrapping** | Use 160-column line width for Java code and Javadoc. | +| **Control Structure New Lines** | Use a new line with single statement if/else blocks. | +| **Author Tags** | Do not use Author Tags. The code is developed and owned by the community. + +### Merging Practices + +Changes should be merged from earlier branches of Accumulo to later branches. Ask the [dev list][dev-mail] for instructions. + +### Project Examples + +A collection of Accumulo example code can be found at the [Accumulo Examples repository][examples]. + +### Website Contributions + +The source for this website is a collection of markdown documents that are converted to HTML using +[Jekyll]. It can be found in the [accumulo-website repo][website-repo]. If you would like to make changes to this website, clone the website repo and edit the markdown: + +``` + git clone https://github.com/apache/accumulo-website.git +``` + +After you have made your changes, follow the instructions in the [README.md][website-readme] to run the website locally and make a pull request on [GitHub][website-repo]. If you have problems installing Jekyll or running the website locally, it's OK to proceed with the pull request. A committer will review your changes before committing them and updating the website. + +### Public API + +Refer to the README in the release you are using to see what packages are in the public API. + +Changes to non-private members of those classes are subject to additional scrutiny to minimize compatibility problems across Accumulo versions. + +### Installing Apache Thrift + +If you activate the ‘thrift’ Maven profile, the build of some modules will attempt to run the Apache Thrift command line to regenerate stubs. If you activate this profile and don’t have Apache Thrift installed and in your path, you will see a warning and your build will fail. For Accumulo 1.5.0 and greater, install Thrift 0.9 and make sure that the ‘thrift’ command is in your path. Watch out for THRIFT-1367; you may need to configure Thrift with –without-ruby. Most developers do not need [...] + +## Committer Documentation + +The links below are provided primarily for the project committers but may be of interest to contributors as well. + +- [Release Management][release] +- [Making a Release][making] +- [Verifying a Release][verifying] + +## Project Governance + +For details about governance policies for the Accumulo project view the following links. + +- [Bylaws][36] +- [Consensus Building][37] +- [Lazy Consensus][38] +- [Voting][39] + + +[1]: #how-to-contribute-to-apache-accumulo +[2]: #project-resources +[3]: #github +[4]: #jira +[5]: #jenkinstravisci +[6]: #create-a-ticket-for-new-bugs-or-feature +[7]: #building-accumulo-from-source +[8]: #checking-out-from-git +[9]: #running-a-build +[10]: #providing-a-contribution +[11]: #proposed-workflow +[12]: #the-implementation +[13]: #contributors +[14]: #developers +[15]: #primary-development +[16]: #reviewing-contributor-changes +[17]: #submit-contribution-via-patch +[18]: #submit-contribution-via-pull-request +[19]: #feature-branches +[20]: #changes-which-affect-multiple-versions-aka-merging +[21]: #code-review-process +[22]: #additional-contributor-information +[23]: #merging-practices +[24]: #public-api +[25]: #coding-practices +[26]: #project-examples +[27]: #website-contributions +[28]: {{ site.baseurl }}/contributor/contrib-projects +[29]: #installing-apache-thrift +[32]: #committer-documentation +[33]: #project-governance +[36]: {{ site.baseurl }}/contributor/bylaws +[37]: {{ site.baseurl }}/contributor/consensusBuilding +[38]: {{ site.baseurl }}/contributor/lazyConsensus +[39]: {{ site.baseurl }}/contributor/voting +[manual]: {{ site.baseurl }}/{{ site.latest_minor_release }}/accumulo_user_manual.html +[quickstart1x]: {{ site.baseurl }}/quickstart-1.x/ +[quickstart2x]: {{ site.baseurl }}/quickstart-2.x/ +[Uno]: https://github.com/astralway/uno +[get-involved]: {{ site.baseurl }}/get_involved +[git]: https://git-scm.com/ +[github]: https://github.com/apache/accumulo +[pulls]: https://github.com/apache/accumulo/pulls +[browse]: https://gitbox.apache.org/repos/asf?p=accumulo.git;a=summary +[mirror]: https://github.com/apache/accumulo +[maven]: https://maven.apache.org/ +[jekyll]: https://jekyllrb.com +[jiraloc]: https://issues.apache.org/jira/browse/ACCUMULO +[jira]: https://www.atlassian.com/software/jira +[newbies]: https://s.apache.org/newbie_accumulo_tickets +[Jenkins]: https://builds.apache.org/view/A/view/Accumulo +[masterbuild]: https://builds.apache.org/job/Accumulo-Master +[18build]: https://builds.apache.org/job/Accumulo-1.8 +[17build]: https://builds.apache.org/job/Accumulo-1.7 +[github-help]: https://help.github.com/ +[ssh]: https://help.github.com/articles/connecting-to-github-with-ssh/ +[forking]: https://help.github.com/articles/fork-a-repo/ +[pom]: https://gitbox.apache.org/repos/asf?p=accumulo.git;a=blob_plain;f=pom.xml;hb=HEAD +[lifecycle]: https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle +[rb]: {{site.baseurl }}/contributor/rb +[rat]: https://creadur.apache.org/rat/apache-rat-plugin +[repo]: https://gitbox.apache.org/repos/asf?p=accumulo.git;a=summary +[pulls]: https://help.github.com/articles/using-pull-requests/ +[dev-mail]: mailto:dev@accumulo.apache.org +[kafka]: https://cwiki.apache.org/confluence/display/KAFKA/Patch+submission+and+review#Patchsubmissionandreview-Simplecontributorworkflow +[examples]: https://github.com/apache/accumulo-examples +[website-repo]: https://github.com/apache/accumulo-website +[website-readme]: https://github.com/apache/accumulo-website/blob/master/README.md +[release]: {{site.baseurl }}/contributor/release-management +[making]: {{site.baseurl }}/contributor/making-release +[verifying]: https://accumulo.apache.org/contributor/verifying-release +[maven]: https://maven.apache.org +[lifecycle]: https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle +[rat]: https://creadur.apache.org/rat/apache-rat-plugin +[pom]: https://gitbox.apache.org/repos/asf?p=accumulo.git;a=blob_plain;f=pom.xml;hb=HEAD + diff --git a/contributor/git.md b/contributor/git.md deleted file mode 100644 index 2a1f552..0000000 --- a/contributor/git.md +++ /dev/null @@ -1,451 +0,0 @@ ---- -title: Git -redirect_from: /git ---- - -[Git](https://git-scm.com) 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 - -The most likely 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](mailto: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. - -1. 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. - -2. Releases are considered extremely onerous and time-consuming so no emphasis - is placed on rapid iterations or development-cycles. - -3. 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. - -4. 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][1]. - -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. - -1. Ensure you configured Git with your information - - `git config --global user.name 'My Name' && git config --global user.email - 'myname@mydomain.com'` - -2. Clone the Accumulo repository: - - `git clone https://gitbox.apache.org/repos/asf/accumulo.git accumulo` - -3. or update your local copy: - - `git fetch && git fetch --tags` - -4. 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` - -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](https://zachholman.com/talk/more-git-and-github-secrets/) - (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.` - -6. 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` - -7. 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//accumulo.git branch=ACCUMULO-12345 - -A second alternative is to use Github's "Pull Requests" feature against the -[Apache Accumulo account](https://github.com/apache/accumulo). Notifications of -new pull-requests from Github should automatically be sent to -[dev@accumulo.apache.org](mailto: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](https://www.apache.org/dev/new-committers-guide#cla): -"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](https://www.apache.org/licenses/LICENSE-2.0.txt). -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: - -1. Checkout the branch for the major version which the patch is intended: - - `git checkout 1.5` - -2. Verify the changes introduced by the patch: - - `git apply --stat ACCUMULO-12345.patch` - -3. Verify that the patch applies cleanly: - - `git apply --check ACCUMULO-12345.patch` - -4. If all is well, apply the patch: - - `git am --signoff < ACCUMULO-12345.patch` - -5. When finished, push the changes: - - `git push origin 1.5` - -6. 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: - -1. Add their repository as a remote to your repository - - `git remote add some_name ${repository}` - -2. Fetch the refs from the given repository - - `git fetch ${repository}` - -3. Merge in the given branch to your local branch - - `git merge some_name/${branch}` - -4. 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](https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging) -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 effect 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 `/ACCUMULO-[-description]`. - -1. Create a branch off of `master`. - - `git checkout /ACCUMULO- master` - -2. Create the feature, committing early and often to appropriately outline the -"story" behind the feature and it's implementation. - -3. 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` - -4. 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` - -5. Continue steps 2 through 4 until the feature is complete. - -6. 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 /ACCUMULO-` - - * **Rebase and merge** -- keeps all feature-branch commits - co-located: - - `git fetch && git rebase origin/master && git checkout master && git merge /ACCUMULO-` - - * **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 /ACCUMULO-` - -### 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. - -0. **Precondition**: choose the right branch to start! (lowest, applicable version - for the change) - -1. Get your changes fixed for that earliest version. - -2. Switch to the next highest version which future minor versions will be - released (non-EOL major release series). - -3. `git-merge` the branch from #1 into the current. - -4. 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` - -5. 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: - -1. [Make a release candidate][making] -2. Create a branch for the release candidate from the `x.y` branch, - named something like `x.y.z'-RCN`. -3. Test and Vote -4. Create a GPG-signed tag with the correct final name: `x.y.z'` -5. 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: - -1. [Make a release candidate][making] -2. Create a tag of the release candidate from the `x.y` branch, - named something like `x.y.0-RCN`. -3. Test and Vote -4. Create a GPG-signed tag with the correct final name: `x.y.0` -5. 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: - -1. The main source tree. This will track the standard trunk, branches, tags - structure from Subversion for Apache Accumulo. - -2. One repository for every project in - [contrib](https://svn.apache.org/repos/asf/accumulo/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](https://git-wip-us.apache.org/repos/asf) 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 request that each repository will also need to -be configured to properly mirror to the [ASF Github](https://github.com/apache) -account to provide the same functionality with current have via the git+svn -mirror. Same change needs to be applied for the [Apache hosted](https://git.apache.org) -mirror'ing. - -## Mailing lists - -It should be noted in the INFRA request that commit messages should be sent to -[commits@accumulo.apache.org](mailto:commits@accumulo.apache.org). The subject -can be decided on using the [provided -variables](https://git-wip-us.apache.org/docs/switching-to-git#contents). - -# Examples - -For the sake of clarity, some examples of common situations are included below. - -## Releasing 1.6.0 - -1. Branch from `master` to `1.6` - - `git checkout master && git branch 1.6` - -2. Tag `1.6.0-RC1` from the just created `1.6` branch - - `git tag 1.6.0-RC1 1.6` - -3. Test, vote, etc. and tag from 1.6.0-RC1 - - `git -s tag 1.6.0 1.6.0-RC1` - -4. Delete the RC tag, if desired. - - `git tag -d 1.6.0-RC1 && git push --delete origin 1.6.0-RC1` - -5. Ensure `master` contains all features and fixes from `1.6.0` - - `git checkout master && git merge 1.6` - -6. Update the project version in `master` to 1.7.0-SNAPSHOT - - -[1]: https://cwiki.apache.org/confluence/display/KAFKA/Patch+submission+and+review#Patchsubmissionandreview-Simplecontributorworkflow -[making]: {{ site.baseurl }}/contributor/making-release diff --git a/contributor/index.md b/contributor/index.md deleted file mode 100644 index 329f4a9..0000000 --- a/contributor/index.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Contributor Guide ---- - -This page contains resources and documentation for Accumulo contributors. Any documentation that is helpful -to Accumulo users should go in the [Accumulo User Manual][manual]. - -## External project resources - -* [JIRA] for tracking issues -* [GitHub] for code reviews (via pull requests) -* [Jenkins] & [TravisCI] for automated builds - -## Development docs - -* [Source Guide][source] -* [Git Workflow][git] -* [Versioning][versioning] -* [Contrib Projects][contrib-projects] -* [Review Board][rb] - -## Release guides - -* [Making a release][making] -* [Verifying a release][verifying] - -## Project governance - -* [Bylaws](/contributor/bylaws) -* [Consensus Building](/contributor/consensusBuilding) -* [Lazy Consensus](/contributor/lazyConsensus) -* [Voting](/contributor/voting) - -[manual]: {{ site.baseurl }}/{{ site.latest_minor_release }}/accumulo_user_manual.html -[JIRA]: https://issues.apache.org/jira/browse/ACCUMULO -[GitHub]: https://github.com/apache/accumulo/pulls -[Jenkins]: https://builds.apache.org/view/A/view/Accumulo -[TravisCI]: https://travis-ci.org/apache/accumulo -[source]: {{ "/contributor/source" | relative_url }} -[git]: {{ "/contributor/git" | relative_url }} -[versioning]: {{ "/contributor/versioning" | relative_url }} -[contrib-projects]: {{ "/contributor/contrib-projects" | relative_url }} -[rb]: {{ "/contributor/rb" | relative_url }} -[making]: {{ "/contributor/making-release" | relative_url }} -[verifying]: {{ "/contributor/verifying-release" | relative_url }} -[bylaws]: {{ "/contributor/bylaws" | relative_url }} -[consensus-building]: {{ "/contributor/consensusBuilding" | relative_url }} -[lazyConsensus]: {{ "/contributor/lazyConsensus" | relative_url }} -[voting]: {{ "/contributor/voting" | relative_url }} diff --git a/contributor/rb.md b/contributor/rb.md index 3630e09..ab05d11 100644 --- a/contributor/rb.md +++ b/contributor/rb.md @@ -10,7 +10,9 @@ be used to support development in the context of the 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. +seeking review prior to pushing changes can also benefit similarly. It should +be noted that more recently the use of GitHub has been overtaking the use of +Review Board for code reviews. ## Roles for Review Board diff --git a/contributor/release-management.md b/contributor/release-management.md new file mode 100644 index 0000000..c31472c --- /dev/null +++ b/contributor/release-management.md @@ -0,0 +1,119 @@ +--- +title: Release Management +redirect_from: /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: + +1. [Make a release candidate][making] +2. Create a branch for the release candidate from the `x.y` branch, + named something like `x.y.z'-RCN`. +3. Test and Vote +4. Create a GPG-signed tag with the correct final name: `x.y.z'` +5. 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: + +1. [Make a release candidate][making] +2. Create a tag of the release candidate from the `x.y` branch, + named something like `x.y.0-RCN`. +3. Test and Vote +4. Create a GPG-signed tag with the correct final name: `x.y.0` +5. 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: + +1. The main source tree. This will track the standard trunk, branches, tags + structure from Subversion for Apache Accumulo. + +2. One repository for every project in + [contrib](https://svn.apache.org/repos/asf/accumulo/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](https://git-wip-us.apache.org/repos/asf) 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 request that each repository will also need to +be configured to properly mirror to the [ASF Github](https://github.com/apache) +account to provide the same functionality with current have via the git+svn +mirror. Same change needs to be applied for the [Apache hosted](https://git.apache.org) +mirror'ing. + +## Mailing lists + +It should be noted in the INFRA request that commit messages should be sent to +[commits@accumulo.apache.org](mailto:commits@accumulo.apache.org). The subject +can be decided on using the [provided +variables](https://git-wip-us.apache.org/docs/switching-to-git#contents). + +# Examples + +For the sake of clarity, some examples of common situations are included below. + +## Releasing 1.6.0 + +1. Branch from `master` to `1.6` + + `git checkout master && git branch 1.6` + +2. Tag `1.6.0-RC1` from the just created `1.6` branch + + `git tag 1.6.0-RC1 1.6` + +3. Test, vote, etc. and tag from 1.6.0-RC1 + + `git -s tag 1.6.0 1.6.0-RC1` + +4. Delete the RC tag, if desired. + + `git tag -d 1.6.0-RC1 && git push --delete origin 1.6.0-RC1` + +5. Ensure `master` contains all features and fixes from `1.6.0` + + `git checkout master && git merge 1.6` + +6. Update the project version in `master` to 1.7.0-SNAPSHOT + + +[1]: https://cwiki.apache.org/confluence/display/KAFKA/Patch+submission+and+review#Patchsubmissionandreview-Simplecontributorworkflow +[making]: {{ site.baseurl }}/contributor/making-release diff --git a/contributor/source.md b/contributor/source.md deleted file mode 100644 index bf7701a..0000000 --- a/contributor/source.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: Source Code and Developers Guide -skiph1fortitle: true -redirect_from: /source ---- - -
    -
    Quick Links
    -
    - Accumulo source - Master build on Jenkins - Accumulo JIRA -
    -
    - -## Source Code - -### Apache Accumulo - -Apache Accumulo® source code is maintained using [Git][git] version control -([browse][cgit]|[checkout][anongit]). It builds with [Apache Maven][maven]. - -Instructions for configuring git are [here][git-instr]. - -### Contrib Projects - -Accumulo has a number of [contrib projects][contrib] that maintain their own code repositories and release schedules. - -### Project Website - -The source for this website is a collection of markdown documents that are converted to HTML using -[Jekyll]. It can be found in the [accumulo-website repo][website-repo]. If you would like to make changes to -this website, clone the website repo and edit the markdown: - - git clone https://github.com/apache/accumulo-website.git - -After you have made your changes, follow the instructions in the [README.md][website-readme] to run the website -locally and make a pull request on [GitHub][website-repo]. If you have problems installing Jekyll or running the -website locally, it's OK to proceed with the pull request. A committer will review your changes before committing -them and updating the website. - -## Developer's Guide - -### Building - -#### Installing Apache Thrift - -If you activate the 'thrift' Maven profile, the build of some modules will attempt to run the Apache Thrift command line to regenerate -stubs. If you activate this profile and don't have Apache Thrift installed and in your path, you will see a warning and -your build will fail. For Accumulo 1.5.0 and greater, install Thrift 0.9 and make sure that the 'thrift' command is in your path. -Watch out for THRIFT-1367; you may need to configure Thrift with --without-ruby. Most developers do not -need to install or modify the Thrift definitions as a part of developing against Apache Accumulo. - -#### Checking out from Git - -To check out the code: - - git clone https://gitbox.apache.org/repos/asf/accumulo.git - -#### Running a Build - -Accumulo uses [Apache Maven][maven] to handle source building, testing, and packaging. To build Accumulo, you will need to use Maven version 3.0.5 or later. - -You should familiarize yourself with the [Maven Build Lifecycle][lifecycle], as well as the various plugins we use in our [POM][pom], in order to understand how Maven works and how to use the various build options while building Accumulo. - -To build from source (for example, to deploy): - - mvn package -Passemble - -This will create a file accumulo-*-SNAPSHOT-dist.tar.gz in the assemble/target directory. Optionally, append `-DskipTests` if you want to skip the build tests. - -To build your branch before submitting a pull request, you'll probably want to run some basic "sunny-day" integration tests to ensure you haven't made any grave errors, as well as `checkstyle` and `findbugs`: - - mvn verify -Psunny - -To run specific unit tests, you can run: - - mvn package -Dtest=MyTest -DfailIfNoTests=false - -Or to run the specific integration tests MyIT and YourIT (and skip all unit tests), you can run: - - mvn verify -Dtest=NoSuchTestExists -Dit.test=MyIT,YourIT -DfailIfNoTests=false - -There are plenty of other options. For example, you can skip findbugs with `mvn verify -Dfindbugs.skip` or checkstyle `-Dcheckstyle.skip`, or control the number of forks to use while executing tests, `-DforkCount=4`, etc. You should check with specific plugins to see which command-line options are available to control their behavior. Note that not all options will result in a stable build, and options may change over time. - -If you regularly switch between major development branches, you may receive errors about improperly licensed files from the [RAT plugin][1]. This is caused by modules that exist in one branch and not the other leaving Maven build files that the RAT plugin no longer understands how to ignore. - -The easiest fix is to ensure all of your current changes are stored in git and then cleaning your workspace. - - $> git add path/to/file/that/has/changed - $> git add path/to/other/file - $> git clean -df - -Note that this git clean command will delete any files unknown to git in a way that is irreversible. You should check that no important files will be included by first looking at the "untracked files" section in a ```git status``` command. - - $> git status - # On branch master - nothing to commit (working directory clean) - $> mvn package - { maven output elided } - $> git checkout 1.6.1-SNAPSHOT - Switched to branch '1.6.1-SNAPSHOT' - $> git status - # On branch 1.6.1-SNAPSHOT - # Untracked files: - # (use "git add ..." to include in what will be committed) - # - # mapreduce/ - # shell/ - nothing added to commit but untracked files present (use "git add" to track) - $> git clean -df - Removing mapreduce/ - Removing shell/ - $> git status - # On branch 1.6.1-SNAPSHOT - nothing to commit (working directory clean) - -### Continuous Integration - -Accumulo uses [Jenkins][jenkins] for automatic builds. - - [Master][masterbuild] - - [1.7 Branch][17build] - - [1.6 Branch][16build] - -### Issue Tracking - -Accumulo [tracks issues][jiraloc] with [JIRA][jira]. Every commit should reference a JIRA ticket of the form ACCUMULO-#. - -### Merging Practices - -Changes should be merged from earlier branches of Accumulo to later branches. Ask the [dev list][devlist] for instructions. - -### Public API - -Refer to the README in the release you are using to see what packages are in the public API. - -Changes to non-private members of those classes are subject to additional scrutiny to minimize compatibility problems across Accumulo versions. - -### Coding Practices - -{: .table} -| **License Header** | Always add the current ASF license header as described in [ASF Source Header][srcheaders]. | -| **Trailing Whitespaces** | Remove all trailing whitespaces. Eclipse users can use Source→Cleanup option to accomplish this. | -| **Indentation** | Use 2 space indents and never use tabs! | -| **Line Wrapping** | Use 160-column line width for Java code and Javadoc. | -| **Control Structure New Lines** | Use a new line with single statement if/else blocks. | -| **Author Tags** | Do not use Author Tags. The code is developed and owned by the community. | - -### Code Review - -Accumulo has [guidelines for using Review Board][rb] to support code reviews. - -### IDE Configuration Tips - -#### Eclipse - -* Download Eclipse [formatting and style guides for Accumulo][styles]. -* Import Formatter: Preferences > Java > Code Style > Formatter and import the Eclipse-Accumulo-Codestyle.xml downloaded in the previous step. -* Import Template: Preferences > Java > Code Style > Code Templates and import the Eclipse-Accumulo-Template.xml. Make sure to check the "Automatically add comments" box. This template adds the ASF header and so on for new code. - -#### IntelliJ - - * Formatter [plugin][intellij-formatter] that uses eclipse code style xml. - -[16build]: https://builds.apache.org/job/Accumulo-1.6 -[17build]: https://builds.apache.org/job/Accumulo-1.7 -[1]: https://creadur.apache.org/rat/apache-rat-plugin -[anongit]: git://git.apache.org/accumulo.git -[cgit]: https://gitbox.apache.org/repos/asf?p=accumulo.git;a=summary -[contrib]: {{ "/contributor/contrib-projects" | relative_url }} -[devlist]: mailto:dev@accumulo.apache.org -[git-instr]: https://gitbox.apache.org -[git]: https://git-scm.com -[github]: https://github.com/apache/accumulo -[website-repo]: https://github.com/apache/accumulo -[website-readme]: https://github.com/apache/accumulo-website/blob/master/README.md -[hook]: https://gitbox.apache.org/repos/asf?p=accumulo-website.git;a=blob_plain;f=_devtools/git-hooks/post-commit;hb=master -[intellij-formatter]: https://code.google.com/p/eclipse-code-formatter-intellij-plugin -[jekyll]: https://jekyllrb.com -[jenkins]: https://jenkins.io -[jira]: https://www.atlassian.com/software/jira -[jiraloc]: https://issues.apache.org/jira/browse/ACCUMULO -[lifecycle]: https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle -[masterbuild]: https://builds.apache.org/job/Accumulo-Master -[maven]: https://maven.apache.org -[pom]: https://gitbox.apache.org/repos/asf?p=accumulo.git;a=blob_plain;f=pom.xml;hb=HEAD -[rb]: {{ "/contributor/rb" | relative_url }} -[site-canon]: https://accumulo.apache.org -[srcheaders]: https://www.apache.org/legal/src-headers -[styles]: https://gitbox.apache.org/repos/asf?p=accumulo.git;a=tree;f=contrib;hb=HEAD diff --git a/contributor/verifying-release.md b/contributor/verifying-release.md index 515589d..b2adbdb 100644 --- a/contributor/verifying-release.md +++ b/contributor/verifying-release.md @@ -11,7 +11,7 @@ trumps anything written here. ## Versioning -Accumulo has adopted [Semantic Versioning][versioning] and follows their rules and guidelines. +Accumulo has adopted [Semantic Versioning][semver] and follows their rules and guidelines. ## Testing basics @@ -127,6 +127,6 @@ own NOTICE file. The contents of the Apache Thrift NOTICE file should be include [4]: https://www.apache.org/legal/resolved [5]: https://www.apache.org/legal [examples]: https://github.com/apache/accumulo-examples -[versioning]: {{ site.baseurl }}/contributor/versioning +[semver]: http://semver.org/spec/v2.0.0.html [at]: https://github.com/apache/accumulo-testing [at-readme]: https://github.com/apache/accumulo-testing/blob/master/README.md diff --git a/css/accumulo.scss b/css/accumulo.scss index 09d7d1e..a032242 100644 --- a/css/accumulo.scss +++ b/css/accumulo.scss @@ -9,7 +9,7 @@ table { } th, td { - padding: 10px 100px 10px 5px; + padding: 10px 40px 10px 5px; border-bottom: 1px solid #ddd; } diff --git a/pages/mailing_list.md b/pages/contact-us.md similarity index 64% rename from pages/mailing_list.md rename to pages/contact-us.md index 256d332..a9d978d 100644 --- a/pages/mailing_list.md +++ b/pages/contact-us.md @@ -1,11 +1,23 @@ --- -title: Mailing Lists -permalink: /mailing_list/ +title: Contact Us +permalink: /contact-us/ +redirect_from: + - /mailing_list/ + - /get_involved/ --- -All Accumulo mailing lists are in the accumulo.apache.org domain. Please note -that search providers linked on this page are not part of the [official Apache -mailing list archives][lists]. +Below are ways to get in touch with the Apache Accumulo community. + +## Issues + +Accumulo uses [JIRA] to track bugs and new features. Before creating an issue, you will need to create +an [Apache JIRA account][jira-signup]. + +## Mailing Lists + +The Accumulo mailing lists are for general discussions, questions, and announcements. While you can read the archives +using the links below, it's best to subscribe to the `user` and `dev` (if you contribute) mailing lists to +follow discussions as they happen. {: .table } | Name | Description | Read | Follow | Post | @@ -15,6 +27,23 @@ mailing list archives][lists]. | **commits** | Code changes | [ Archive][C_A] | [ Subscribe][C_SU] [ Unsubscribe][C_UN] | | | **notifications** | Automated notifications (JIRA, etc.) | [ Archive][N_A] | [ Subscribe][N_SU] [ Unsubscribe][N_UN] | | +## IRC + +Drop by and chat about Accumulo at [#accumulo][accumulo-irc] on [freenode]. + +## Contributions + +Contributions to Apache Accumulo are welcome! If you are interested, read [how to contribute][contribute]. If you need help finding something to work on, send a message to our `dev` mailing list and we'll help you find a task that interests you. + +## Events + +Attend Accumulo events such as [Accumulo Summit][summit] and meetups hosted by [Accumulo Users Group - DC VA MD][meetup-dc]. + +[JIRA]: https://issues.apache.org/jira/browse/ACCUMULO +[jira-signup]: https://issues.apache.org/jira/secure/Signup!default.jspa + + + [U_A]: https://lists.apache.org/list.html?user@accumulo.apache.org {: .btn .btn-primary .btn-xs } [U_SU]: mailto:user-subscribe@accumulo.apache.org @@ -47,4 +76,8 @@ mailing list archives][lists]. [N_UN]: mailto:notifications-unsubscribe@accumulo.apache.org {: .btn .btn-danger .btn-xs } -[lists]: https://lists.apache.org +[summit]: http://accumulosummit.com +[meetup-dc]: https://www.meetup.com/Accumulo-Users-DC/ +[accumulo-irc]: irc://chat.freenode.net/accumulo +[freenode]: https://freenode.net/ +[contribute]: /how-to-contribute/ diff --git a/pages/get_involved.md b/pages/get_involved.md deleted file mode 100644 index 96415ef..0000000 --- a/pages/get_involved.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Get Involved -permalink: /get_involved/ ---- - -You don't need to be a software developer to contribute to -Apache Accumulo. To be successful, this project -requires a huge range of different skills, levels of involvement, and degrees of -technical expertise. So, if you want to get involved in Apache Accumulo, there -is almost certainly a role for you. - -We are looking for people to: - - - provide feedback - - write or update documentation - - help new users - - recommend the project to others - - test the code and report bugs - - fix bugs - - give us feedback on required features - - write and update the software - - create artwork - - translate to different languages - - anything you can see that needs doing - -All of these contributions help to keep the project active and strengthen -the community. The project team and the broader community will -therefore welcome and encourage participation, and attempt to make it -as easy as possible for people to get involved. - -Want to get started now? Check out [open issues labeled for "newbies"][newbie]. If you need help, use the mailing list information below to reach out. If the issue you choose deals with code, you should read the developer's guide section. - -## Mailing lists and chat - -Your first engagement with the project should be to subscribe to our -[mailing lists][mlist]. Apache Accumulo developers and community members -hang out in the #accumulo channel on irc.freenode.net. - -## Contributor Guide - -See the [contributor guide][contrib] for recommended practices in interacting with our source code. -Take a look at [Accumulo's OpenHub page][openhub] for an analysis of the code base. - -## Conferences and Meetups - -* [Accumulo Summit][summit] -* [Accumulo Users Group - DC VA MD][meetup-dc] -* Look for [Accumulo Meetups in your area][meetup] - -## Decision Making - -The most important thing about engaging with any Apache project is that everyone -is equal. All people with an opinion are entitled to express that opinion and, where -appropriate, have it considered by the community. - -To some, the idea of having to establish consensus in a large and distributed team -sounds inefficient and frustrating. Don't despair though, The Apache Way has a -set of simple processes to ensure things proceed at a good pace. - -In ASF projects we don't like to vote. We reserve that for the few things that need -official approval for legal or process reasons (e.g. a release or a new committer). -Most of the time we work with the consensus building techniques documented below. - -### Lazy Consensus - -[Lazy consensus][lazy] is the first, and possibly the most important, consensus building -tool we have. Essentially, lazy consensus means that you don't need to get explicit -approval to proceed, but you need to be prepared to listen if someone objects. - -### Consensus Building - -Sometimes, lazy consensus is not appropriate. In such cases, it is necessary to -make a proposal to the mailing list and discuss options. There are mechanisms -for quickly showing your support or otherwise for a proposal and -[building consensus][consensus] amongst the community. - -Once there is a consensus, people can proceed with the work under the [lazy -consensus][lazy] model. - -### Voting - -Occasionally a "feel" for consensus is not enough. Sometimes we need to -have a measurable consensus. For example, when [voting] in new committers or -to approve a release. - -[newbie]: https://s.apache.org/newbie_accumulo_tickets -[mlist]: {{ site.baseurl }}/mailing_list -[summit]: http://accumulosummit.com -[meetup-dc]: https://www.meetup.com/Accumulo-Users-DC/ -[meetup]: https://www.meetup.com/find/?keywords=accumulo -[contrib]: {{ site.baseurl }}/contributor/ -[openhub]: https://www.openhub.net/p/accumulo -[lazy]: {{ site.baseurl }}/contributor/lazyConsensus -[consensus]: {{ site.baseurl }}/contributor/consensusBuilding -[voting]: {{ site.baseurl }}/contributor/voting - diff --git a/pages/how-to-contribute.md b/pages/how-to-contribute.md new file mode 100644 index 0000000..0e0a562 --- /dev/null +++ b/pages/how-to-contribute.md @@ -0,0 +1,150 @@ +--- +title: How To Contribute +permalink: /how-to-contribute/ +redirect_from: /contributor/ +--- + +Contributions are welcome to all Apache Accumulo repositories. While most contributions are code, +there are other ways to contribute to Accumulo: + +* answer questions on mailing lists +* review pull requests +* verify and test new releases +* update the Accumulo website and documentation + +Contributions are reviewed (via GitHub pull requests) by +the community before being merged by a committer. + +This document provides basic instructions for contributing to Accumulo. If you are looking for more information, check out the more comprehensive [contributor guide](/contributors-guide/). + +## Issues + +Any contribution should have a corresponding issue. Accumulo uses [JIRA] for issue tracking. Before creating an issue, +you will need to create an [Apache JIRA account][jira-signup]. If you need help finding an issue to work on, check out +the [open issues labeled for newbies][newbie-issues] or [contact us][contact]. + +## Repositories + +Contributions can be made to the following repositories. While the general contribution workflow is +described below, repositories have special instructions in their `CONTRIBUTING.md` file which can be +viewed by clicking on `contribute` in the Links column below. + +| Repository | Links | Description +| ------------------------------- | -------- | ----------- +| [Accumulo][a] | [contribute][ac] | Core Project +| [Accumulo Website][w] | [contribute][wc] | Source for this website +| [Accumulo Examples][e] | [contribute][ec] | Accumulo example code +| [Accumulo Testing][t] | [contribute][tc] | Accumulo test suites such as continuous ingest and random walk +| [Accumulo Docker][d] | [contribute][dc] | Source for Accumulo Docker image +| [Accumulo Wikisearch][s] | [contribute][sc] | Accumulo example application that indexes and queries Wikipedia data + +## Contribution workflow + +1. Create an [Apache JIRA account][jira-signup] (for issue tracking) and [GitHub account][github-join] (for pull requests). +1. Find an [issue][newbie-issues] to work on or create one that describes the work that you want to do. +1. [Fork] and [clone] the GitHub repository that you want to contribute to. +1. Create a branch in the local clone of your fork. +``` + git checkout -b accumulo-4321 +``` +1. Do work and commit to your branch. You can reference [this link][messages] for a guide on how to write good commit log messages. +1. Ensure you works satisfies the guidelines laid out in the `CONTRIBUTING.md` file. +1. If needed, squash to the minimum number of commits. For help on squashing commits, see this [tutorial][squash-tutorial] or [StackOverflow answer][squash-stack]. +1. [Push] your branch to your fork. +``` + git push origin accumulo-4321 +``` +1. Create a [Pull Request] on GitHub to the appropriate repository. If the work is not complete and the Pull Request is for feedback, please put `[WIP]` in the subject. +1. At least one committer (and others in the community) will review your pull request and add any comments to your code. +1. Push any changes from the review to the branch as new commits so the reviewer only needs to review new changes. Please avoid squashing commits after the review starts. Squashing makes it hard for the reviewer to follow the changes. +1. Repeat this process until a reviewer approves the pull request. +1. When the review process is finished, all commits on the pull request may be squashed by a committer. Please avoid squashing as it makes it difficult for the committer to know if they are merging what was reviewed. + +## Coding Guidelines + +* If a change needs to go into multiple branches of Accumulo, it should be merged into earlier branches then later branches. +* Accumulo follows [semver] for its public API. Accumulo lists which packages are public API in its [README.md][accumulo-readme]. +* Every file requires the ASF license header as described in [ASF Source Header][srcheaders]. +* Remove all trailing whitespaces. Eclipse users can use Source→Cleanup option to accomplish this. +* Use 2 space indents and never use tabs! +* Use 160-column line width for Java code and Javadoc. +* Use a new line with single statement if/else blocks. +* Do not use Author Tags. The code is developed and owned by the community. + +## Code Editors + +Feel free to use any editor when contributing Accumulo. If you are looking for a recommendation, many Accumulo +developers use [IntelliJ][intellij] or [Eclipse][eclipse]. Below are some basic instructions to help you get started. + +### IntelliJ + +1. Download and install [IntelliJ][intellij] +1. Clone the Accumulo repository that you want to work on. + ```shell + git clone https://github.com/apache/accumulo.git + ``` +1. [Import][intellij-import] the repository as a Maven project into IntelliJ +1. (Optional) Download and import `Eclipse-Accumulo-Codestyle.xml` from Accumulo's [contrib][accumulo-contrib] directory + * Import via `File` > `Settings` > `Code Style` and clicking on cog wheel + +### Eclipse + +1. Download and install [Eclipse][eclipse]. +1. Clone the Accumulo repository that you want to work on. + ```shell + git clone https://github.com/apache/accumulo.git + ``` +1. [Import][eclipse-import] the repository as a Maven project into Eclipse +1. (Optional) Download and import Eclipse formatting and style guides from Accumulo's [contrib][accumulo-contrib] directory + * Import Formatter: `Preferences` > `Java` > `Code Style` > `Formatter` and import the `Eclipse-Accumulo-Codestyle.xml` downloaded in the previous step. + * Import Template: `Preferences` > `Java` > `Code Style` > `Code Templates` and import the `Eclipse-Accumulo-Template.xml`. Make sure to check the "Automatically add comments" box. This template adds the ASF header and so on for new code. + +## Helpful Links + +* **Build resources** - [TravisCI] & [Jenkins][jenkins] ([Master][masterbuild], [1.8 Branch][18build], [1.7 Branch][17build]) +* **Releases** - [Making a release][making], [Verifying a release][verifying] + +For more details, see the [contributor guide](/contributors-guide/). + +[newbie-issues]: https://s.apache.org/newbie_accumulo_tickets +[contact]: /contact-us/ +[a]: https://github.com/apache/accumulo +[ac]: https://github.com/apache/accumulo/blob/master/CONTRIBUTING.md +[w]: https://github.com/apache/accumulo-website +[wc]: https://github.com/apache/accumulo-website/blob/master/CONTRIBUTING.md +[e]: https://github.com/apache/accumulo-examples +[ec]: https://github.com/apache/accumulo-examples/blob/master/CONTRIBUTING.md +[t]: https://github.com/apache/accumulo-testing +[tc]: https://github.com/apache/accumulo-testing/blob/master/CONTRIBUTING.md +[d]: https://github.com/apache/accumulo-docker +[dc]: https://github.com/apache/accumulo-docker/blob/master/CONTRIBUTING.md +[s]: https://github.com/apache/accumulo-wikisearch +[sc]: https://github.com/apache/accumulo-wikisearch/blob/master/CONTRIBUTING.md +[jira-signup]: https://issues.apache.org/jira/secure/Signup!default.jspa +[github-join]: https://github.com/join +[manual]: {{ site.baseurl }}/{{ site.latest_minor_release }}/accumulo_user_manual.html +[JIRA]: https://issues.apache.org/jira/browse/ACCUMULO +[GitHub]: https://github.com/apache/accumulo/pulls +[Jenkins]: https://builds.apache.org/view/A/view/Accumulo +[TravisCI]: https://travis-ci.org/apache/accumulo +[making]: {{ "/contributor/making-release" | relative_url }} +[verifying]: {{ "/contributor/verifying-release" | relative_url }} +[Fork]: https://help.github.com/articles/fork-a-repo/ +[Pull Request]: https://help.github.com/articles/about-pull-requests/ +[Push]: https://help.github.com/articles/pushing-to-a-remote/ +[clone]: https://help.github.com/articles/cloning-a-repository/ +[masterbuild]: https://builds.apache.org/job/Accumulo-Master +[18build]: https://builds.apache.org/job/Accumulo-1.8 +[17build]: https://builds.apache.org/job/Accumulo-1.7 +[srcheaders]: https://www.apache.org/legal/src-headers +[styles]: https://gitbox.apache.org/repos/asf?p=accumulo.git;a=tree;f=contrib;hb=HEAD +[accumulo-readme]: https://github.com/apache/accumulo/blob/master/README.md#api +[semver]: http://semver.org/spec/v2.0.0.html +[eclipse]: https://www.eclipse.org/ +[eclipse-import]: https://stackoverflow.com/questions/2061094/importing-maven-project-into-eclipse +[intellij]: https://www.jetbrains.com/idea/ +[intellij-import]: https://www.jetbrains.com/help/idea/maven.html#maven_import_project_start +[accumulo-contrib]: https://github.com/apache/accumulo/tree/master/contrib +[messages]: https://chris.beams.io/posts/git-commit/ +[squash-tutorial]: http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html +[squash-stack]: https://stackoverflow.com/questions/5189560/squash-my-last-x-commits-together-using-git diff --git a/pages/quickstart-1.x.md b/pages/quickstart-1.x.md new file mode 100644 index 0000000..265f97f --- /dev/null +++ b/pages/quickstart-1.x.md @@ -0,0 +1,104 @@ +--- +title: Quickstart (1.x) +permalink: /quickstart-1.x/ +--- + +## Installing Accumulo + +This document covers installing Accumulo on single and multi-node environments. Either [download] or [build] a binary distribution of Accumulo from source code. Unpack as follows: + +``` +cd +tar xzf /accumulo-X.Y.Z-bin.tar.gz +cd accumulo-X.Y.Z +``` + +Accumulo has some optional native code that improves its performance and stability. Before configuring Accumulo attempt to build this native code with the following command. + +``` +./bin/build_native_library.sh +``` + +If the command fails, its ok to continue with setup and resolve the issue later. + +## Configuring + +The Accumulo conf directory needs to be populated with initial config files. The following script is provided to assist with this. Run the script and answer the questions. When the script ask about memory-map type, choose Native if the build native script was successful. Otherwise choose Java. + +``` +./bin/bootstrap_config.sh +``` + +The script will prompt for memory usage. Please note that the footprints are only for the Accumulo system processes, so ample space should be left for other processes like hadoop, zookeeper, and the accumulo client code. If Accumulo worker processes are swapped out and unresponsive, they may be killed. + +After this script runs, the conf directory should be populated and now a few edits are needed. + +## Secret + +Accumulo coordination and worker processes can only communicate with each other if they share the same secret key. To change the secret key set `instance.secret` in `conf/accumulo-site.xml`. Changing this secret key from the default is highly recommended. + +## Dependencies + +Accumulo requires running [Zookeeper][zookeeper] and [HDFS][hdfs] instances. Also, the Accumulo binary distribution does not include jars for Zookeeper and Hadoop. When configuring Accumulo the following information about these dependencies must be provided. + +- **Location of Zookeepers :** Provide this by setting `instance.zookeeper.host` in `conf/accumulo-site.xml`. +- **Where to store data :** Provide this by setting `instance.volumes` in `conf/accumulo-site.xml`. If your namenode is running at __192.168.1.9:9000__ and you want to store data in `/accumulo` in HDFS, then set `instance.volumes` to `hdfs://192.168.1.9:9000/accumulo`. +- **Location of Zoookeeper and Hadoop jars :** Setting `ZOOKEEPER_HOME` and `HADOOP_PREFIX` in `conf/accumulo-env.sh` will help Accumulo find these jars. + +If Accumulo has problems later on finding jars, then run `bin/accumulo classpath` to print out info about where Accumulo is finding jars. If the settings mentioned above are correct, then inspect `general.classpaths` in `conf/accumulo-site.xml`. + +## Initialization + +Accumulo needs to initialize the locations where it stores data in Zookeeper and HDFS. The following command will do this. + +```./bin/accumulo init``` + +The initialization command will prompt for the following information: + +- **Instance name :** This is the name of the Accumulo instance and its Accumulo clients need to know it inorder to connect. +- **Root password :** Initialization sets up an initial Accumulo root user and prompts for its password. This information will be needed to later connect to Accumulo. + +## Multiple Nodes + +Skip this section if running Accumulo on a single node. Accumulo has coordinating, monitoring, and worker processes that run on specified nodes in the cluster. The following files should be populated with a newline separated list of node names. Must change from localhost. + +- `conf/masters` : Accumulo primary coordinating process. Must specify one node. Can specify a few for fault tolerance. +- `conf/gc` : Accumulo garbage collector. Must specify one node. Can specify a few for fault tolerance. +- `conf/monitor` : Node where Accumulo monitoring web server is run. +- `conf/slaves` : Accumulo worker processes. List all of the nodes where tablet servers should run in this file. +- `conf/tracers` : Optional capability. Can specify zero or more nodes. + +The Accumulo, Hadoop, and Zookeeper software should be present at the same location on every node. Also the files in the conf directory must be copied to every node. There are many ways to replicate the software and configuration, two possible tools that can help replicate software and/or config are [pdcp] and [prsync]. + +## Starting Accumulo + +The Accumulo scripts use ssh to start processes on remote nodes. Before attempting to start Accumulo, [passwordless ssh][ssh] must be setup on the cluster. + +After configuring and initializing Accumulo, use the following command to start it. + +```./bin/start-all.sh``` + +## First steps + +Once the `start-all.sh` script completes, use the following command to run the Accumulo shell. + +```./bin/accumulo shell -u root``` + +Use your web browser to connect the Accumulo monitor page on port 9995. + +```http://:9995/``` + +When finished, use the following command to stop Accumulo. + +```./bin/stop-all.sh``` + + + +[download]: http://accumulo.apache.org/downloads/ +[build]: {{ "/contributors-guide#building-accumulo-from-source" | relative_url }} +[zookeeper]: http://zookeeper.apache.org/ +[hdfs]: https:/hadoop.apache.org/ +[pdcp]: https://code.google.com/p/pdsh/ +[prsync]: https://code.google.com/p/parallel-ssh/ +[ssh]: https://www.tecmint.com/ssh-passwordless-login-using-ssh-keygen-in-5-easy-steps/ + -- To stop receiving notification emails like this one, please contact ['"commits@accumulo.apache.org" '].