accumulo-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] mikewalch commented on a change in pull request #37: Accumulo 4714 Create landing page for new developers
Date Thu, 01 Jan 1970 00:00:00 GMT
mikewalch 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_r150603358
 
 

 ##########
 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&reg; 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 git@github.com:<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:
   I know you didn't write this section but I think this section and other verbose ones like
it can be simplified.  If want to do it, feel free.  Otherwise, I might do a PR later to cut
this section down.

----------------------------------------------------------------
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:
users@infra.apache.org


With regards,
Apache Git Services

Mime
View raw message