Contributing code changes
Checkout source codeAnchor fork fork
- Fork the project from Github at https://github.com/apache/ambari if you haven't already
Clone this fork:
Code Block language bash git clone https://github.com/username/ambari.git /target/path
Set upstream remote:
Code Block cd /target/path git remote add upstream https://gitbox.apache.org/repos/asf/ambari.
git
- Open an Apache JIRA corresponding to the issue at hand
Use the Apache JIRA for posting design docs and having design discussions (adding detailed descriptions, comments, etc)
Create a patch and upload to the Apache JIRA. The patch should be named AMBARI-XXXX.patch for trunk patches and AMBARI-XXXX_YYYY.patch for branch patches, where XXXX is the JIRA ID and YYYY is the name of the branch (for example, AMBARI-1234_branch-1.7.0.patch). If the patch is for a release branch, both trunk patch and branch patch must be uploaded.
Mark the patch as Patch Available by clicking on the “Submit Patch” button (Note: if the patch is for a private branch, then it will cause an integration failure in the test runner, in this case you may not perform "Submit Patch")
Wait for the "Hadoop QA" process to post feedback on the patch. This typically takes 30 mins to an hour and reports back on unit test results, license header compliance, presence of new tests, etc, on the JIRA itself.
If "Hadoop QA" checks do not pass but you think the feedback is invalid, state the reasons why you believe it is invalid.
Once "Hadoop QA" checks pass (or if there's a valid reason for ignoring the checks), create a ReviewBoard for the patch (see Using Review Board section below) and request two Ambari committers (more would not hurt) to review the patch via the code review process below
Please note that if the patch is not involved - one committer should suffice
On review completion and any further updates, the reviewers give +1 for the patch
A +1 from an Ambari committer is mandatory before any patch can be committed (+1 from a non committer, though useful, does not count toward this requirement)
There should be 2 +1's from Ambari committers for changes that are involved or if the patch is going into a release branch
NOTE: Be sure to include tests in the patch. If tests are not applicable, provide a good explanation for not having a test case.
After the reviewer(s) has approved the patch, the assignee of the JIRA is responsible for getting it committed if that person is a committer. If not, one of the reviewers needs to commit.
If the patch is intended to go into a release branch, make sure that the patch is committed to both the release branch and trunk.
Refer to https://cwiki.apache.org/confluence/display/AMBARI/How+to+Commit on how to commit
After committing to git, resolve the Apache JIRA as Fixed.
All unit tests must pass after applying the patch.
Also, any new files must contain Apache 2.0 license headers
Do not use tabs. Set your IDE to convert tabs into spaces instead.
Do not use non-ASCII characters
Do not use Windows newline characters. Use UNIX newline characters instead.
Make sure that you are checking in all dependencies/new files; after committing, the build should work on clean checkout
Make sure that the clock is set up correctly on your machine.
Review Process
Ambari uses ReviewBoard for code reviews.
All Ambari related code reviews, at ReviewBoard, can be found at https://reviews.apache.org/groups/Ambari/
Using ReviewBoard
You may need to create a ReviewBoard login. Once you login add yourself to the "Ambari" group.
git
Keep your Fork Up to Date
Code Block language bash # 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
Code Block 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
Code Block 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
...
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.
Contribution Flow
...
.
...