mikewalch closed pull request #36: Updated contributor guide URL: https://github.com/apache/accumulo-website/pull/36
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..675198c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,32 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +# 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..2c671bf 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -36,11 +36,10 @@ <li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown" href="#">Community<span class="caret"></span></a> <ul class="dropdown-menu"> - <li><a href="{{ site.baseurl }}/get_involved">Get Involved</a></li> - <li><a href="{{ site.baseurl }}/mailing_list">Mailing Lists</a></li> + <li><a href="{{ site.baseurl }}/contact-us">Contact Us</a></li> + <li><a href="{{ site.baseurl }}/how-to-contribute">How To Contribute</a></li> <li><a href="{{ site.baseurl }}/people">People</a></li> <li><a href="{{ site.baseurl }}/related-projects">Related Projects</a></li> - <li><a href="{{ site.baseurl }}/contributor/">Contributor Guide</a></li> </ul> </li> </ul> diff --git a/contributor/build.md b/contributor/build.md new file mode 100644 index 0000000..c17ca74 --- /dev/null +++ b/contributor/build.md @@ -0,0 +1,82 @@ +--- +title: Building Accumulo +redirect_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 + +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][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) + +[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/contrib-projects.md b/contributor/contrib-projects.md deleted file mode 100644 index d02b972..0000000 --- a/contributor/contrib-projects.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Contrib Projects -redirect_from: /contrib ---- - -Apache Accumulo is a complex distributed system. In order to minimize that -complexity, for both operators and developers, the project maintains contrib -repositories for instructive applications and code that builds interoperability -between Accumulo and other systems. This helps minimize the set of dependencies -needed when building or installing Accumulo, keeps the build time down, and -allows the contrib projects to follow their own release schedule. - -## Existing Contrib Projects - -Each of the below contrib project handles their own development and release -cycle. For information on what version(s) of Accumulo they work with, see the -documentation for the individual project. - -### Instamo Archetype - -A Maven Archetype that automates the customization of Instamo to quickly spin -up an Accumulo process in memory. - -The Apache Accumulo Instamo Archetype uses [Git][gitbook] version control -([browse][instamo-browse]|[checkout][instamo-checkout]). It builds with [Apache -Maven][maven-proj]. See the section [Contributing to Contrib][contrib2] for -instructions on submitting issues and patches. - -### Wikisearch Application - -A complex application example that makes use of most of the Accumulo feature -stack. The Wikisearch application provides an example of indexing and querying -Wikipedia data within Accumulo. It is a great place to start if you want to get -familiar with good development practices building on Accumulo. - -For details on setting up the application, see the project's [README.md][wiki-readme] -where you can also read an overview and some performance numbers. - -The Apache Accumulo Wikisearch Example uses [Git][gitbook] version control -([browse][wikisearch-browse]|[checkout][wikisearch-checkout]). It builds with -[Apache Maven][maven-proj]. See the section [Contributing to Contrib][contrib2] for -instructions on submitting issues and patches. - -### Hama Integration - -An implementation for running [Bulk Synchronous Parallel (BSP) -algorithms][bsp-alg] implemented via [Apache Hama][hama] on top of data stored -in Accumulo. - -The Apache Accumulo BSP implementation uses [Git][gitbook] version control -([browse][bsp-browse]|[checkout][bsp-checkout]). It builds with [Apache -Maven][maven-proj]. See the section [Contributing to Contrib][contrib2] for -instructions on submitting issues and patches. - -## Contributing to Contrib - -All contributions to the various Apache Accumulo contrib projects should follow -the [same process used in the primary project][git-process]. All contributions -should have a corresponding issue filed in the [contrib component in the -Accumulo issue tracker][jira-component]. - -## Adding a new Contrib Project - -Proposals for new contrib projects should be sent to the [Accumulo mailing -list][mailing-list] for [developers][mail-with-subj]. - -If an example application only makes use of a single Accumulo feature, it is -probably better off as an Accumulo version-specific example. You can see -several of these demonstrative applications in the [simple example -codebase][examples-simple] and the related published documentation for versions -[1.7][17EXAMPLES] and [1.6][16EXAMPLES]. - -[gitbook]: http://git-scm.com -[instamo-browse]: https://gitbox.apache.org/repos/asf?p=accumulo-instamo-archetype.git;a=summary -[instamo-checkout]: https://gitbox.apache.org/repos/asf/accumulo-instamo-archetype.git -[maven-proj]: https://maven.apache.org -[wiki-readme]: https://github.com/apache/accumulo-wikisearch/blob/master/README.md -[wikisearch-browse]: https://gitbox.apache.org/repos/asf?p=accumulo-wikisearch.git;a=summary -[wikisearch-checkout]: https://gitbox.apache.org/repos/asf/accumulo-wikisearch.git -[bsp-alg]: https://hama.apache.org/hama_bsp_tutorial -[hama]: https://hama.apache.org -[bsp-browse]: https://gitbox.apache.org/repos/asf?p=accumulo-bsp.git;a=summary -[bsp-checkout]: https://gitbox.apache.org/repos/asf/accumulo-bsp.git -[git-process]: git#the-implementation -[jira-component]: https://issues.apache.org/jira/browse/ACCUMULO/component/12316610 -[mailing-list]: mailing_list -[mail-with-subj]: mailto:[email protected]?subject=[Accumulo+Contrib+Proposal] -[examples-simple]: https://gitbox.apache.org/repos/asf?p=accumulo-examples.git;a=summary -[16EXAMPLES]: 1.6/examples -[17EXAMPLES]: 1.7/examples -[contrib2]: #contributing-to-contrib 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 deleted file mode 100644 index 3630e09..0000000 --- a/contributor/rb.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Using Review Board ---- - -The Apache Software Foundation provides an [instance][rbinstance] of -[Review Board][rb] (RB) for projects to use in code reviews. Here is how RB can -be used to support development in the context of the -[Apache Accumulo bylaws][bylaws]. - -Contributors to Accumulo are encouraged to use RB for non-trivial patches and -any time feedback is desired. No one is required to use RB, but its ready -availability and better interface for feedback can help with reviews. Committers -seeking review prior to pushing changes can also benefit similarly. - -## Roles for Review Board - -### Optional Pre-Commit Review - -Accumulo operates under the [Commit-Then-Review][ctr] (CtR) policy, so code -review does not need to occur prior to commit. However, a committer may opt to -hold a code review before commit for changes that, in their opinion, would -benefit from additional attention. RB can be used to conduct such code reviews. - -### Consensus Approval after a Code Change Veto - -Code changes are approved by lazy approval, with consensus approval following -a veto (see the [Actions][actions] section of the bylaws). RB can be used -to coordinate a consensus approval vote by providing a convenient view of the -code change under consideration. The vote itself must still be held on the -developer mailing list. - -## Guidelines for Posting a Review - -* It is best to post a git-generated patch as the basis for a review. RB does - not support patches containing multiple commits, so either squash commits - first, or submit a diff spanning the changeset. The `rbt` and `post-review` - tools generate diffs. -* Strive to make your changes small. Reviewers are less likely to want to - trudge through a review with lots of changes, and are more likely to miss - problems. -* Begin the summary of the review with a JIRA issue number. A review must - always be associated with a JIRA issue. The issue number should also be - entered in the "Bugs" field of the review, providing a link to JIRA. -* The "Branch" field should contain the name of the branch that the code change - is based on (e.g., the base of your git feature branch). -* Include the "accumulo" user group as reviewers. Also include specific people - as individual reviewers, even if they are in the "accumulo" group, if you - deem them of primary importance for the review (e.g., you have been working - out problems with the review with them, they are expert in the area). -* Use the description to summarize the change under review. Include helpful - instructions to the reviewers here. -* Describe any testing done on the change. It is not expected that reviewers - will do their own testing, and they may reject the review if you have not - done sufficient testing yourself. -* Avoid submitting generated code for review if it can be reproduced by a - reviewer. - -After the review is published, set the status of the associated JIRA issue to -"Patch Available" as a signal to reviewers. Also, link to the review from the -issue (More -> Link -> Web Link) to help viewers of the issue find the review -and assess its progress. - -## Guidelines for Reviewing Code - -* Try to associate comments with relevant lines of code in the review. -* By default, each comment opens a review issue. If a comment pertains to - something that should not block the review from completing successfully, then - clear the "Open an issue" checkbox before saving your feedback. Examples that - might qualify as non-issues: minor formatting/whitespace issues, spelling - mistakes, general background questions. -* If a review looks good, be sure to "Ship It" by either using the "Ship It!" - button or by submitting a general review with the "Ship It" checkbox checked. - -## Guidelines for Completing a Review - -These guidelines do not apply to consensus approval votes, since the vote -completion depends on the votes registered in the developer mailing list. - -* Use your judgement for the number of "Ship It"s you want to receive to - consider a review passed. Usually, getting one "Ship It" is enough to proceed - with a commit. It is recommended that the "Ship It" be from a committer who - is a neutral party not involved in the change under review. -* Use your judgement for the minimum time length you set for the review. Simple - changes can be up for just a day, while complex ones should take up to seven. -* Review time should be extended in the face of problems discovered in the - review. Update the review with improved code instead of discarding (i.e., - closing unsuccessfully) it and beginning a new one. -* A review should not be "submitted" (i.e., closed successfully) unless there - are no outstanding issues. Check with reviewers to ensure that their issues - are resolved satisfactorily. -* A review should be "discarded" if the code requires major rework or it - becomes obvious it should never be committed (due to design changes, - becoming overcome by events, being back-burnered, etc.). -* Don't leave a review open indefinitely. Once you have received sufficient - feedback to submit or discard it, do so. If there has been no activity for - some time, discard the review. A new one can always be created later. - -Once you've closed a review as submitted, if you are unable to commit your -changes yourself, attach the final version of them to the relevant JIRA issue. -They should be in the form of a patch containing a single commit, -[per the final steps of the contribution process][contributor]. - -[rbinstance]: https://reviews.apache.org -[rb]: https://www.reviewboard.org -[bylaws]: {{ "/contributor/bylaws" | relative_url }} -[ctr]: https://www.apache.org/foundation/glossary#CommitThenReview -[actions]: {{ "/contributor/bylaws#actions" | relative_url }} -[contributor]: {{ "/contributor/git#contributors" | relative_url }} 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 ---- - -<div class="panel panel-default pull-right"> -<div class="panel-heading">Quick Links</div> -<div class="list-group"> -<a href="https://gitbox.apache.org/repos/asf?p=accumulo.git;a=summary"; class="list-group-item"><i class="fa fa-external-link"></i> Accumulo source</a> -<a href="https://builds.apache.org/job/Accumulo-Master"; class="list-group-item"><i class="fa fa-external-link"></i> Master build on Jenkins</a> -<a href="https://issues.apache.org/jira/browse/ACCUMULO"; class="list-group-item"><i class="fa fa-external-link"></i> Accumulo JIRA</a> -</div> -</div> - -## 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 <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) - -### Continuous Integration - -Accumulo uses [Jenkins][jenkins] for automatic builds. - -<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.7/lastBuild/buildStatus"; style="height: 1.1em"> [1.7 Branch][17build] - -<img src="https://builds.apache.org/job/Accumulo-1.6/lastBuild/buildStatus"; style="height: 1.1em"> [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:[email protected] -[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/contributor/versioning.md b/contributor/versioning.md deleted file mode 100644 index 9f5c39d..0000000 --- a/contributor/versioning.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Versioning -redirect_from: /versioning ---- - -The Apache Accumulo PMC closed a vote on 2014/12/12 which adopted [Semantic Versioning 2.0.0][1] as -the reference document on the meaning and requirements of the versions of Apache Accumulo. Semantic -versioning requires a definition of a public API: this definition is unchanged over previous releases and -can be found in section 9 of the [README][2]. A copy of the specification is included here, licensed under -[Creative Commons - CC BY 3.0][3]: - -## Specification - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" -in this document are to be interpreted as described in RFC 2119. - -1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist -strictly in documentation. However it is done, it should be precise and comprehensive. - -2. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain -leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase -numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0. - -3. Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST -be released as a new version. - -4. Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be -considered stable. - -5. Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent -on this public API and how it changes. - -6. Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix -is defined as an internal change that fixes incorrect behavior. - -7. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the -public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if -substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. -Patch version MUST be reset to 0 when minor version is incremented. - -8. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public -API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented. - -9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following -the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. -Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal -version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements -as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92. - -10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following -the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST -NOT be empty. Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the -build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85. - -11. Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating -the version into major, minor, patch and pre-release identifiers in that order (Build metadata does not figure into precedence). -Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, -minor, and patch versions are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When major, minor, and patch -are equal, a pre-release version has lower precedence than a normal version. Example: 1.0.0-alpha < 1.0.0. Precedence for two -pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier -from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and -identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence -than non-numeric identifiers. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the -preceding identifiers are equal. Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < -1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0. - - -[1]: http://semver.org/spec/v2.0.0 -[2]: https://gitbox.apache.org/repos/asf?p=accumulo.git;a=blob;f=README.md;hb=refs/heads/master -[3]: https://creativecommons.org/licenses/by/3.0 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..998a73c 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,21 @@ mailing list archives][lists]. | **commits** | Code changes | [<span class="glyphicon glyphicon-search"/> Archive][C_A] | [<span class="glyphicon glyphicon-plus"/> Subscribe][C_SU] [<span class="glyphicon glyphicon-remove"/> Unsubscribe][C_UN] | | | **notifications** | Automated notifications (JIRA, etc.) | [<span class="glyphicon glyphicon-search"/> Archive][N_A] | [<span class="glyphicon glyphicon-plus"/> Subscribe][N_SU] [<span class="glyphicon glyphicon-remove"/> 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 our [Contributor Guide][contributor]. 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/[email protected] {: .btn .btn-primary .btn-xs } [U_SU]: mailto:[email protected] @@ -47,4 +74,8 @@ mailing list archives][lists]. [N_UN]: mailto:[email protected] {: .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/ +[contributor]: /contributor/ 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..de3766c --- /dev/null +++ b/pages/how-to-contribute.md @@ -0,0 +1,151 @@ +--- +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 + +This document describes how to make contributions which are reviewed (via GitHub pull requests) by +the community before being merged by a committer. + +## 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 the `C` in the Links column below. + +| Repository | Links | Description +| ------------------------------- | -------- | ----------- +| [Accumulo][a] | [C][ac] | Core Project +| [Accumulo Website][w] | [C][wc] | Source for this website +| [Accumulo Examples][e] | [C][ec] | Accumulo example code +| [Accumulo Testing][t] | [C][tc] | Accumulo test suites such as continuous ingest and random walk +| [Accumulo Docker][d] | [C][dc] | Source for Accumulo Docker image +| [Accumulo Wikisearch][s] | [C][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 +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 or StackOverflow answer. +1. [Push] your branch to your fork. + ``` + git push origin fluo-301 + ``` +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, most 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-contib] 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.7 Branch][17build], [1.6 Branch][16build]) +* **Development** - [Building Accumulo][build], [Git Workflow][git] +* **Releases** - [Making a release][making], [Verifying a release][verifying] +* **Project governance** - [Bylaws](/contributor/bylaws), [Consensus Building](/contributor/consensusBuilding), [Lazy Consensus](/contributor/lazyConsensus), [Voting](/contributor/voting) + +[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 +[build]: {{ "/contributor/build" | relative_url }} +[git]: {{ "/contributor/git" | 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 }} +[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 +[16build]: https://builds.apache.org/job/Accumulo-1.6 +[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 ---------------------------------------------------------------- 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
