Page History

Contributing code changes

1. Anchor
   fork fork

   Checkout source code

1. • 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

• http://www.apache.org/legal/src-headers.html 

• 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.

1. • git

2. 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.

3. 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.

   1. Find an existing Apache JIRA that the change pertains to

   1. 1. 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

      2. Look for existing pull requests that are linked from the JIRA, to understand if someone is already working on the JIRA

   2. If the change is new, then create a new JIRA:
      1. Provide a descriptive Title
      2. 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.
      3. Fill the required fields:
         1. Issue Type. Bug and Task are the most frequently used issue types in Ambari.
         2. Priority. Their meaning is roughly:
            1. Blocker: pointless to release without this change as the release would be unusable to a large minority of users
            2. Critical: a large minority of users are missing important functionality without this, and/or a workaround is difficult
            3. Major: a small minority of users are missing important functionality without this, and there is a workaround
            4. Minor: a niche use case is missing some support, but it does not affect usage or is easily worked around
            5. Trivial: a nice-to-have change but unlikely to be any problem in practice otherwise
         3. Component. Choose the components that are affected by this change. Choose from here - Ambari Components
         4. Affects Version. For Bugs, assign at least one version that is known to exhibit the problem or need the change
      4. Do not include a patch file; pull requests are used to propose the actual change.
         
         

4. 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.

1. 1. Commit and Push changes

      1. 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

      2. Make changes to the code and commit them to the newly created branch.
      3. Run all the tests that are applicable and make sure that all unit tests pass

      4. Push your changes

         Code Block
         git push origin AMBARI-XXXXX-branch-2.6

   2. Create Pull Request

      1. 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.

         1. The pull request title should be of the form [AMBARI-xxxx] Title, where AMBARI-xxxx is the relevant JIRA number

         2. 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
         3. 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.
         4. The related JIRA will automatically have a link to the Pull Request in Github. Mark the status of JIRA as "In Progress"
            
            
   3. 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.

1. 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.
2. 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.
3. 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

...

.

...