Contributing code changes
Checkout source code
- Fork the project from Github at https://github.com/apache/ambari if you haven't already
Clone this fork:
git clone https://github.com/username/ambari.git /target/path
Set upstream remote:
cd /target/path git remote add upstream https://gitbox.apache.org/repos/asf/ambari.git
Keep your Fork Up to Date
# Fetch from upstream remote git fetch upstream # Checkout the branch that needs to sync git checkout trunk # Merge with remote git merge upstream/trunk
Repeat these steps for all the branches that needs to be synced with the remote.
JIRA
Apache Ambari uses JIRA to track issues including bugs and improvements, and uses Github pull requests to manage code reviews and code merges. Major design changes are discussed in JIRA and implementation changes are discussed in pull requests after a pull request is created.
Find an existing Apache JIRA that the change pertains to
- Do not create a new JIRA if the change is minor and relates to an existing JIRA; add to the existing discussion and work instead
Look for existing pull requests that are linked from the JIRA, to understand if someone is already working on the JIRA
- If the change is new, then create a new JIRA:
- Provide a descriptive Title
- Write a detailed Description. For bug reports, this should ideally include a short reproduction of the problem. For new features, it may include a design document.
- Fill the required fields:
- Issue Type. Bug and Task are the most frequently used issue types in Ambari.
- Priority. Their meaning is roughly:
- Blocker: pointless to release without this change as the release would be unusable to a large minority of users
- Critical: a large minority of users are missing important functionality without this, and/or a workaround is difficult
- Major: a small minority of users are missing important functionality without this, and there is a workaround
- Minor: a niche use case is missing some support, but it does not affect usage or is easily worked around
- Trivial: a nice-to-have change but unlikely to be any problem in practice otherwise
- Component. Choose the components that are affected by this change. Choose from here - Ambari Components
- Affects Version. For Bugs, assign at least one version that is known to exhibit the problem or need the change
- Do not include a patch file; pull requests are used to propose the actual change.
Pull Request
Apache Ambari uses Github pull requests to review and merge changes to the source code. Before creating a pull request, one must have a fork of apache/ambari checked out. Follow instructions in step 1 to create a fork if you haven't already.
Commit and Push changes
Create a branch AMBARI-XXXXX-branchName before starting to make any code changes. Ex: If the Fix Version of the JIRA you are working on is 2.6.2, then create a branch based on branch-2.6
git checkout branch-2.6 git pull upstream branch-2.6 git checkout -b AMBARI-XXXXX-branch-2.6
- Make changes to the code and commit them to the newly created branch.
- Run all the tests that are applicable and make sure that all unit tests pass
Push your changes
git push origin AMBARI-XXXXX-branch-2.6
Create Pull Request
- Navigate to your fork in Github and create a pull request. The pull request needs to be opened against the branch you want the patch to land.
The pull request title should be of the form [AMBARI-xxxx] Title, where AMBARI-xxxx is the relevant JIRA number
- If the pull request is still a work in progress, and so is not ready to be merged, but needs to be pushed to Github to facilitate review, then add [WIP] after the AMBARI-XXXX
- Consider identifying committers or other contributors who have worked on the code being changed. Find the file(s) in Github and click “Blame” to see a line-by-line annotation of who changed the code last. You can add @username in the PR description to ping them immediately or add them to the list of reviewers to the pull request.
- The related JIRA will automatically have a link to the Pull Request in Github. Mark the status of JIRA as "In Progress"
- Navigate to your fork in Github and create a pull request. The pull request needs to be opened against the branch you want the patch to land.
- Repeat the above two steps for patches that needs to land in multiple branches. Ex: If a patch needs to be committed to branches branch-2.6 and trunk, then you need to create two branches and open two pull requests by following the above steps.
Review Process
Ambari uses Github for code reviews. All committers are required to follow the instructions in this page and link their github accounts with gitbox to gain Merge access to apache/ambari in github.
To try out the changes locally, you can checkout the pull request locally by following the instructions in this guide.
- Committers can try out the changes locally and either approve or give their feedback on the pull request by submitting a review on the pull request. More help can be found here.
- If more changes are required, the committers can mention their feedbcak on the lines of code that requires changes. The author of the pull request can then update the code and push another commit to the same branch to update the pull request and notify the committers.
- The pull request can be merged if atleast one committer has approved it.
To submit a patch for review
- Click on "New Review Request"
- Select "ambari" from the drop-down and upload a diff file
- Go to the next page
- Add a summary
- Names of at least two reviewers that are familiar with that code, please refer to Code Review Guidelines for a list of committers that have volunteered to review a certain code area (In case patch is simple and less involved - one reviewer is ok)
- Select ambari as the group
- Enter the name of the branch(es), e.g., "trunk", "branch-x.y"
- Type in the Ambari JIRA id
- Add description of the fix
- Be sure to fill out "Testing Done" section to describe what testing has been done (e.g., tested X, Y, and Z scenarios end-to-end on a live cluster), post unit test results, etc.
- Add a link to the ReviewBoard URL to the JIRA
- Go to JIRA Menu --> More --> Link --> Web Link (Link Text should be ReviewBoard)
- [if applicable] Fill the optional fields as needed.
- [if applicable] Add the unit test summary to the request
- Publish the review
- After the review is marked "Ship It" you can optionally attach the final patch to the JIRA.
- Mark the review as closed
- On the ReviewBoard portal Close --> Submitted
For reviewers
Reviewers, after you are satisfied with the patch, mark "Ship It" through the ReviewBoard or "+1" to the JIRA.
Apache Ambari Committers
Please read more on Apache Committers at: http://www.apache.org/dev/committers.html
In general a contributor that makes sustained, welcome contributions to the project may be invited to become a committer, though the exact timing of such invitations depends on many factors. Sustained contributions over 6 months is a welcome sign of contributor showing interest in the project. A contributor receptive to feedback and following development guidelines stated above is a good sign for being a committer to the project. We have seen contributors contributing 20-30 patches become committers but again this is very subjective and can vary on the patches submitted to the project. Ultimately it is the Ambari PMC that suggests and votes for committers in the project.