milleruntime commented on a change in pull request #37: Accumulo 4714 Create landing page for new developers URL: https://github.com/apache/accumulo-website/pull/37#discussion_r150626212
########## File path: 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. + +<img src="https://builds.apache.org/job/Accumulo-Master/lastBuild/buildStatus"; style="height: 1.1em"> [Master][masterbuild] + +<img src="https://builds.apache.org/job/Accumulo-1.8/lastBuild/buildStatus"; style="height: 1.1em"> [1.8 Branch][18build] + +<img src="https://builds.apache.org/job/Accumulo-1.7/lastBuild/buildStatus"; style="height: 1.1em"> [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 [email protected]:<account name>/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 <file>..." 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 Review comment: This page is way too long. You are right about some sections being simplified but I feel like a lot of sections could just be dropped. This section and the proposed workflow could be dropped. It should just be workflow, I don't think people care for a lengthy history lesson. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
