You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »

Provides information describing how a committer reviews and approves pull requests.

Initial Set-Up

Step 1: Configure git E-Mail

Configure git to use your Apache e-mail address.

git config --global user.email myusername@apache.org

Step 2: Check trafodion-contributors Group

Check that your GitHub user is a public member in the trafodion-contributors group. This allows some permissions with the Jenkins test server.

https://github.com/orgs/trafodion-contributors/people

Step 3: Set Up Work Space

Set up your work space so that you can merge pull requests.

 

Do the following:

  • In VNC/Gnome environment, either add to .bashrc or type at your current shell:

    unset SSH_ASKPASS


  • Pushing code to the Apache repository requires password authentication.

  • Ensure that your work space is cloned from GitHub:

    git clone https://github.com/apache/incubator-trafodion

  • Ensure that you have a remote pointing to the Apache repository. (Setting only the push URL with user name does not seem to work. This means that fetching the apache remote prompts for a password, but it is ignored. You can hit return without entering password, and fetch still works! You must enter password only when pushing to apache remote.)

    git remote add apache https://USERNAME@git-wip-us.apache.org/repos/asf/incubator-trafodion.git

Automated Testing

You can interact with Jenkins testing via pull request (PR) comments. All of these commands should start with "jenkins," to not confuse other users. You can add more to the end of the message if you want. Jenkins just pattern matches the string, and will ignore trailing comments.

  • If an unknown user submits a PR, then Jenkins automation will post a message to GitHub asking if it is okay to test.
    • Review the pull request. If the code is not malicious and is okay to test, post a comment jenkins, ok
  • If the author is a trusted contributor, you can add them to a white-list of known users.
  • New commits to the PR will trigger a new build. You can also trigger a retest without a new commit.
    • Post a comment: jenkins, retest
  • For extensive or risky changes, you may want to run a fuller set of tests.
    • Post a comment: jenkins, extra test
    • This runs additional jobs, running several suites o CDH and HDP distros, as well as full phoenix suite.

Validate Review Criteria

 

The project committee (PPMC) has agreed that the following review criteria are used for contributions:

  • Code Review(s)
  • Time available for comments
  • Testing
    • Be sure that you wait for all pending tests!
    • New commits, even those that are just merging with latest master branch, trigger new test run.
  • Legal
  • Other 

Guidelines for Code Reviews 

Anyone can be a reviewer: participating in the review process is a great way to learn about the Trafodion development processes.

 

Some things are necessary to keep in mind when doing code reviews:

  1. C code should comply with the [[cplusplus-guidelines,C Guidelines]].

  2. The code should look like the code around it, to make the code more uniform and easier to read.

  3. New test cases should be implemented as described in Modifying Tests.

 

General Flow 

Review is a conversation that works best when it flows back and forth. Submitters need to be responsive to questions asked in comments, even if the score is +0 from the reviewer. Likewise, reviewers should not use a negative score to elicit a response if they are not sure the patch should be changed before merging.

 

For example, if there is a patch submitted which a reviewer cannot fully understand because there are changes that aren’t documented in the commit message or code documentation, this is a good time to issue a negative score. Patches need to be clear in their commit message and documentation.

 

In almost all cases, a negative review should be accompanied by clear instructions for the submitter how they might fix the patch.

 

There may be more specific items to be aware of inside the projects' documentation for contributors.

 

Contributors may notice a review that has several +1’s from other reviewers, passes the functional tests, etc. but the code still has not been merged. As only committers can approve code for merging, you can help things along by getting a committers’s attention in dev@trafodion.incubator.apache.org and letting them know there is a changeset with lots of positive reviews and needs final approval.

 

Be Aware of Licensing Concerns

Trafodion is developed and provided using the Apache 2.0 license. In order to not compromise that license, we must be careful about accepting code contributions that are not original code. We cannot accept code forked from other open source projects that have a non-permissive license for example.

 

If a reviewer suspects that contributed code is not original without attribution, the reviewer should -1 the change, and in the review comment, state the concern about originality and licensing. If the contributed code is proven to be unoriginal and with an incompatible license, the contribution should be rejected. If this happens, it is recommended that the Trafodion PPMC privately discuss with the contributor the importance of proper licensing and proper attribution or originality. The importance of attribution, originality, and licensing is often difficult for some new contributors, for some students, and for some people from various cultures of origin, and this should be seen as a learning and teaching opportunity.

Merge Pull Requests

 

 

Target Branch

Before beginning, make careful note of what branch you are merging to. At the top of the pull request, you'll see words like, "So-and-so wants to merge n commits into apache:target_branch from github_user:some_other_branch. Most of the time, target_branch will be "master", but occasionally you'll see a release branch instead, e.g., "release1.3". In the instructions below, if the target_branch is not "master", replace "master" with the name of the target branch.

 

 

Step 1: Check Status

Check the pull request status on GitHub, at the bottom of the pull request page. It will tell you if there are any merge conflicts with master branch.

If there are conflicts, either ask the contributor to merge up, or be prepared to resolve the conflicts yourself.

Step 2: Create Local Merge Branch

Create a local merge branch, based on the latest, greatest.

# You will be prompted for password, but you do not have to enter it for fetch. Just hit return.
git fetch apache
git checkout -b mrg_12345 apache/master

Step 3: Fetch Pull Request Branch

Fetch pull request branch to default destination FETCH_HEAD.

git fetch origin +refs/pull/12345/head

Step 4: Merge Locally

Merge locally, giving message that includes JIRA ID.

git merge --no-ff -m "Merge [TRAFODION-XYZ] PR-12345 Whizbang feature" FETCH_HEAD
 OR
git merge --squash FETCH_HEAD
git commit  # edit comment, give good headline and detailed body
            # Also include phrase "This closes #<PR num>" substituting in the pull-request number

NOTES

  • Sometimes for changes with many commits, you might want to squash their branch into a single commit. If so, add the --squash option.
    • On the plus side, squashing a developer branch into single commit puts all the file related changes into a single commit. Easier to find, back-port, etc.
    • On the minus side, squashing breaks the change from the developer history. Be extra careful to edit the comment to clearly identify the developer and combined commit comments. 
  • If you forget the -m option, you end up with a less than helpful default comment.

    • Before you push the commit, you can fix the comment by:

      git commit --amend

Step 5: Additional Checks

Additional checks of what you are preparing to push.

git log apache/master..HEAD
git diff apache/master HEAD

Step 6: Push Changes

Push changes to the Apache repository, specifying the source and the destination branch.

# You will be prompted for your Apache password
git push apache HEAD:master`

Publish Web Site Updates

If the change you are merging includes website or document updates, you should also update the project website. Look for files in the docs/ tree as well as some files in dcs/ and core/rest that affect documents.

For more info on documentation build, see Modifying Documents.

To publish the website:

  1. Fetch changes to be published from the Trafodion master branch (git fetch --all; git checkout apache/master).
  2. Build Trafodion site (source env.sh; mvn post-site).
  3. If there are documentation changes to prior releases, check out those release branch(es) and re-build the affected docs (git checkout apache/releaseX.Y; source env.sh; cd docs/... ; mvn post-site).
  4. git clone https://ApacheUserName@git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git
  5. Checkout asf-site branch (cd incubator-trafodion-site; git checkout -b asf-site origin/asf-site).
  6. Copy content of trafodion build into the incubator-trafodion-site directory (cp -R trafodion/docs/target/*   incubator-trafodion-site/). 
  7. Commit changes (git add --all ; git commit).
  8. Push them back to the apache origin repository to the asf-site branch (git push origin HEAD:asf-site).
  9. Check that the website is refreshed.

Once pushed, Apache gitpubsub takes care of populating http://incubator.trafodion.apache.org with your new changes. If they don’t show up, pushing another commit may work to trigger the automation. Just make an innocuous white-space change to some html file, commit it and push it.

Once published, run https://validator.w3.org against http://trafodion.incubator.apache.org to ensure that there are no broken links.

Completion 

  1. Close Jira, if appropriate, or ask the contributor to do so.
  2. If ASF automation does not close the pull request, ask the contributor to do so.


 

 

  • No labels