Contributing - REEF - Apache Software Foundation

Contributing - REEF - Apache Software Foundation
This project has retired. For details please refer to its
Attic
page.
DUE TO SPAM, SIGN-UP IS DISABLED. Goto
Selfserve wiki signup
and request an account.
REEF
Pages
Page tree
Browse pages
tachments (0)
Page History
Resolved comments
Page Information
View in Hierarchy
View Source
Export to PDF
Export to Word
Copy Page Tree
Jira links
Contributing
Created by
Markus Weimer
, last modified by
Doug Service
on
Jan 25, 2017
First things first: Welcome!
Arriving on this page means that you are interested in helping us out. For that: Welcome and thank you!
REEF is a community driven project and we always welcome new people joining us. We are inviting contributions in many forms to all parts of the project, including:
Bug reports regarding the software, the documentation, the website, guides like this, etc.
Documentation updates, tutorials, examples.
Code: Patches, new features, etc
The majority of this guide will discuss the contribution of code, but that doesn't mean that the other contributions are any less valuable.
Getting started: Join the community.
The first step is to
join the
community by joining our mailing list
. This is where all discussions regarding the project are happening, where we answer each other's questions and where you will find a friendly bunch to welcome you.
If you want to work on the REEF code base, it is a good idea to
learn how to compile and test REEF
Finding things to work on
At any given time, there is any number of
open, unassigned issues on REEF
. There is also a shorter list of
open issues which are good for beginners
. Note that that list doesn't only contain coding tasks, but also documentation, graphics work, the website and so on. We use JIRA to manage all open todos for the project, software or otherwise.
However, some of the items on that list might since have become obsolete or such. Hence, it is always a good idea to get in touch with the rest of the community on the mailing list before getting started.
Code contribution process
While contributing to REEF, you will encounter ASF infrastructure, GitHub infrastructure, and follow ASF and REEF-specific customs. The most important of those customs is to communicate throughout the whole process. That way, the REEF community has a chance to help you along the way.
Before you start the work
An important part of the process comes
before
you start the contribution process. Most issues should first be brought up in the
dev@reef.apache.org
mailing list. If you haven't done so yet,
subscribe to the list
. After discussion, you or one of the other developers will create an Issue on
ASF JIRA
. Again, create an account if you don't have one. Write a succinct description of the Issue, making sure to incorporate any discussion from the mailing list.
Assign the JIRA you've chosen to yourself. This way you're letting the rest of developers know that you're working on it, so that nobody else will start working on it in parallel.
And once you are ready to make changes,
have a look at the coding guidelines
to make sure your code agrees with the rest of REEF.
Creating the contribution as a GitHub Pull Request
REEF uses
GitHub's Pull Requests
as the main method to accept changes:
you fork REEF into your own repository, make changes, and then send a pull request to the GitHub repository. In more detail:
Fork repository
Create branch
Make changes in your local machine
Merge the master branch into your branch
Push commits into the your remote repo (forked)
Send a pull request.
Participate in the code review.
1. Fork repository
First, you need to fork the REEF repository. Go to the
Github repository
mirrored from ASF, and click "Fork" button. Then you will have your own repository. Clone this repository to your local machine:
$ git clone https://github.com/{your_alias}/reef.git
Then, add the apache GitHub repository as upstream:
$ git remote add upstream https://github.com/apache/reef.git
A correct git configuration should look similar to the following, with an origin and upstream:
$ git remote -v
origin https://github.com/{your_alias}/reef.git (fetch)
origin https://github.com/{your_alias}/reef.git (push)
upstream https://github.com/apache/reef.git (fetch)
upstream https://github.com/apache/reef.git (push)
If you have an `apache.org` email address, now is the time to
configure git
to use it:
$ git config user.name "My Name Here"
$ git config user.email myusername@apache.org
2. Create a branch to work on
Before making changes, you have to make sure the issue to resolve (e.g. fix a bug, implement a new feature, etc) is registered in the
REEF JIRA
. Create a branch to address the issue on your own. The name of the branch should reference the issue, e.g.,
REEF-{issue_number}
. You can take a look how others name their branches.
3. Make changes in your local machine
Write the code and make commits as usual. Make sure all new files contain the
ASF licensing header
Make sure to run all tests when you complete your change to avoid any regression. For instructions, see
Java build instructions
and
C# build instructions
4. Merge the master branch into your branch
Before sending a pull request, you should make sure that your branch includes the latest changes in the master branch. Please run the following:
$ git fetch upstream
$ git checkout {your_branch} # Skip this step if you are already on your branch.
$ git merge upstream/master
Resolve the conflicts if exist. Test with the merged code so that it does not break the system.
There are several code quality checks executed as part of the build. If any of them fails, you can re-run it manually to clarify where the violation is.
Java build instructions
have instructions for running checks separately.
Finally, as a courtesy to the merger, you can rebase to master and squash all the commits from your PR into one:
# Rebase
$ git rebase -i upstream/master
In the rebase process, make sure that the contribution is squashed to a single commit. From the list of commits, "pick" the commit in the first line (the oldest), and "squash" the commits in the remaining lines:
pick 7387a49 Comment for first commit
squash 3371411 Comment for second commit
squash 9bf956d Comment for third commit
Chapter 3
and
Chapter 7
of the
Git Book
contains lots of information on what this means.
In this process, git allows you to edit the commit message for the final, squashed commit. This commit message will serve as the description of the pull request and will in all likelihood appear in verbatim in the REEF history. In other words: Spend some time making it good
[REEF-JIRA_ISSUE_NUMBER] THE_TITLE_OF_THE_JIRA

This addressed the issue by
* INSERT_DESCRIPTION_OF_SOMETHING
* INSERT_DESCRIPTION_OF_SOMETHING_ELSE
* ...

JIRA:
[REEF-JIRA_ISSUE_NUMBER](https://issues.apache.org/jira/browse/REEF-JIRA_ISSUE_NUMBER)

Pull request:
This closes #
As you can see, we follow
Markdown syntax
for our commit messages. You can get a good idea how other people write their commit messages by inspecting the output of
git log
5. Push commits into the your remote repo (forked)
You're almost done! Push your commits into your own repo.
$ git push origin HEAD
6. Send a pull request
It is time to send a pull request. If you do not know much about pull request, you may want to read this
article
If you go to the repository at the Github website, you can notice that "Compare & Pull request" button appears. Click the button or move into "pull request" tab if you cannot find the button.
When you create a pull request, you choose the branches to compare and merge. Choose the base as
apache:master
and the head
your_alias}:{branch_name
. The description will be the message of your one commit. Feel free to edit it if you aren't satisfied with your commit message.
Please
update the JIRA issue with a link to the Pull Request.
This triggers an email to the mailing list, which will hopefully result in a committer stepping up for a code review.
7. The code review
REEF follows a review-then-commit (RTC) model. We perform all our code reviews on GitHub: Community members will leave comments on your pull request and suggest changes. You can
have a look at prior pull requests
to get an idea of what to expect. During this process, you may want to change your code. You can do that by pushing additional commits to your branch. Don't worry about squashing the commits into one at this stage. This will be done by the committer once your code is merged into REEF.
When the code review concludes, one of Committers will merge your work into the REEF codebase. Good job!
8. Merge the pull request (Committers only)
If you are committer, you can follow the steps in the
Committer Guide
to merge the pull request. Of course, you won't be merging your own pull requests. Nudge committers as needed to make sure everything gets merged correctly.
Other guides
There are other pages in this area you might be interested in:
.NET Project structure
Building REEF
Git
Linux
Windows
On running tests in Visual Studio
Windows PowerShell Setup
Coding Guidelines
Commit Messages
No labels
Overview
Content Tools
Atlassian Confluence Open Source Project License
granted to Apache Software Foundation.
Evaluate Confluence today
Atlassian Confluence
8.5.31
Printed by Atlassian Confluence 8.5.31
Report a bug
Atlassian News
Atlassian
{"serverDuration": 148, "requestCorrelationId": "ca97d4da2acab8ec"}