This is a tutorial to guide a newbie to complete a new-contributor task and become an open-source contributor of the Alluxio project. Please make sure that the following prerequisites are met before you start: 

1. Have a MacOS or Linux-based computer next to you.
2. Install Git on your computer (download).
3. Sign in to GitHub (login).

Step 1: Fork the Alluxio Repository on Github

First, fork Alluxio repository under your Github account as the destination to push your local change. On the Alluxio repository homepage click the “Fork” button on the top-right corner (as shown in the following figure).

If you happen to fork the repository before, there will be a message like “You've already forked alluxio” shown on Github. 

After completing this step, you have successfully created your own fork of the Alluxio repository under your GitHub account. You can browse this repository at “https://github.com/<YOUR-USERNAME>/alluxio” with “<YOUR-USERNAME>” replaced by your github account ID. 

Step 2: Clone the Repository on Your Computer

Next, create a local clone of Alluxio and download all the files from your fork onto your computer using Git. Open your terminal and run this command:

$ git clone https://github.com/<YOUR-USERNAME>/alluxio.git

This command will create a clone under the alluxio/ directory with all files copied. This step can take up to a few minutes depending on your network speed. Once it completes, you will see output like the following:

Receiving objects: 100% (493591/493591), 137.79 MiB , 5.81 MiB/s, done.Resolving deltas: 100% (241641/241641), done.

Step 3: Configure the Local Repository

Now, we need to configure the local repository a bit before making any contribution. The remaining commands in this tutorial assume the current working directory to be at the root of the cloned repository (alluxio/).

$ cd alluxio

Set up your commit email in Git correctly to help us track and acknowledge your contribution:

$ git config --local user.email "email@example.com

where “email@example.com” should be your email address associated with your Github account. Check your Github profile email settings if you haven’t associated an email with your GitHub account. 

Step 4: Take a New Contributor Task

Browse any of the open New Contributor Alluxio Tasks and find one that is unassigned. In order to assign an issue to yourself, leave a comment in the issue like /assign @yourUserName to indicate that you are working on the issue. You should always assign a ticket to yourself this way before you start working on it, so others in the community know you are working on the ticket.

Now let’s work on a task!

Step 5: Create a Feature Branch in your Clone

Keep all changes for a single issue in its own branch when submitting a change to Alluxio. Create a new branch to work on the New Contributor task you took earlier. To create a branch named “awesome_feature” based on the master branch (the default branch) and switch to this branch, run:

$ git checkout -b awesome_feature master

Now, you can modify the necessary code to address the issue.

Step 6: Create Local Commits

As you are addressing the ticket, you can create local commits of your code. This can be useful when you have finished a well-defined portion of the change. 

You must first stage the files for a commit with:

$ git add <file you changed>

Once the appropriate files are staged, create a local commit of these modifications with:

$ git commit -m "<concise but descriptive commit message>"

Please read the Alluxio coding conventions for more details and tips on how to update the Alluxio source code. For more details on creating commits, please visit instructions on how to create commits.

Step 7: Push Local Change

After you have finished all the changes to address the issue, you are ready to submit a pull request to the Alluxio project! Here are detailed instructions on sending a pull request, but the following is a common way to do it.

Push the branch with your commits to your forked repository in GitHub. For your awesome_feature branch, push to GitHub with:

$ git push origin awesome_feature

Step 8: Create a Pull Request

Open your browser and enter “https://github.com/<YOUR-USERNAME>/alluxio/pull/new/awesome_feature”. You will see the following form to fill in order to create a Pull Request:

It is important to use an effective title for the pull request. Here are some tips and conventions for a great PR title adapted from existing rules.

• Title should be not too long (< ~50 characters) and not too short (descriptive enough)
• Title should start with an imperative verb
  • Examples: Fix Alluxio UI bugs, Refactor Inode caching logic
  • Incorrect: ~~Fixed Alluxio UI bugs~~, ~~Inode caching refactor~~
  • Use one from the list of allowable words to start the title
• The first word of the title should be capitalized
• Title should not end with a period

There are a few exceptions to these rules. Prefixes can be added to the beginning of the title. Prefixes are in all caps and are separated from the rest of the title with a space. Here are the possible prefixes.

• [DOCFIX]: This is for PRs which updates documentation
  • Examples: [DOCFIX] Update the Getting Started guide, [DOCFIX] Add GCS documentation
• [SMALLFIX]: This is for PRs for minor fixes which do not change any logic, like typos
  • Examples: [SMALLFIX] Fix typo in AlluxioProcess, [SMALLFIX] Improve comment style in GlusterFSUnderFileSystem

It is also important to write a good PR description. Notice that all New Contributor issues on Github are assigned with a number. The number can be found after the issue title, like #123. When you create a pull request to address the issue, you should add a link/pointer back to the issue itself. In order to do that you have to add certain text in the pull request description. For example, if your issue number is #123, you should include one of the following in your pull request description.

• Fix Alluxio/new-contributor-tasks#123
• Close Alluxio/new-contributor-tasks#123

Here are some tips and conventions for a great PR description, adapted from existing rules for great commit messages.

Once everything is set, click on the Create pull request button. Congratulations! Your first pull request for Alluxio has been submitted!

Step 9: Complete the Code Review

After the pull request has been submitted, it can be found on the Pull Request page of the Alluxio repository.

After it is submitted, other developers in the community will review your pull request. Others may add comments or questions to your pull request. Tests and checks will also be run against the new changes to validate your changes are safe to merge.

During the code review process, please reply to all comments left by reviewers to track which comments have been addressed and how each comment has been addressed.

Additional code changes may be necessary to address comments from reviewers or fix broken tests and checks. After making the required changes locally, create a new commit and push it to your remote branch. GitHub will detect new changes to the source branch and update the corresponding pull request automatically. An example workflow to update your remote branch:

$ git add <modified files>
$ git commit -m "<another commit message>"
$ git push origin awesome_feature

After all the comments and questions have been addressed in the pull request, reviewers will give your pull request an LGTM ( “Look Good To Me”) and approve the pull request. After at least one approval, a maintainer will merge your pull request into the Alluxio codebase.

Congratulations! You have successfully contributed to Alluxio! Thank you for joining the community!

Next Step

There are multiple levels of tasks in Alluxio. We strongly encourage new contributors to complete two New Contributor tasks before taking on more advanced tasks. New Contributor tasks are quite easy to resolve and do not require too much context within the code. This is a good way to familiarize yourself with the entire process of contributing to the Alluxio project. In addition to these New Contributor tasks, we also have tasks at different levels: 

• easy tasks for beginners which typically only need to modify a single file.
• medium tasks for intermediate which typically need to modify multiple files, but in the same package with the local context. 
• hard tasks for advanced contributors which often require modifying multiple files and understanding the architecture and workflow very well. 

We're looking forward to welcoming new contributors. Join us on Slack channel and become a part of the community today!