Getting Started

To propose code changes, you should be familiar with the Git / Github workflow, including:

.gitconfig

Here's a convenient .git/config file that shows how to:

  • Set up branches
  • Limit fetched branches to master only
  • Fetch PRs from upstream
  • Configure alias to show a pretty formatted git log.

If you have more simple and useful configs to add, feel free to comment on gist.

How to create a pull request

To create a new pull request, follow the next steps:

  1. Fork the github.com/apache/beam repo

  2. Clone your fork, for example:

    $ git clone git@github.com:${GITHUB_USERNAME}/beam
$ cd beam

  3. Add an upstream remote for apache/beam to allow syncing changes into your fork: 

    $ git remote add upstream https://github.com/apache/beam

  4. Create a local branch for your changes: 

    $ git checkout -b someBranch
  5. Make your code change.
  6. Add unit tests for your change.
  7. Ensure tests pass locally.

  8. Commit your change including a reference to the Github issue:

    $ git add <new files>
$ git -am "Description of change (resolves #12345)"

  9. Push your change to your forked repo 

    $ git push --set-upstream origin YOUR_BRANCH_NAME

  10. Browse to the URL of your forked repository and propose a pull request.

  11. Find a committer to review, and mention them by adding R: @username to the review comments


How to create a cherry-pick pull request for an ongoing release branch

To create a new cherry-pick full request, follow these steps:

  1. Make a pull-request with changes to the master branch first,  have it reviewed and merged. As an example, we assume your PR is https://github.com/apache/beam/pull/25000 and you would like to cherry-pick it to Beam 2.56.0 release branch.  We normally only cherry-pick already merged changes to the release branch.

  2. If you already have a clone of Beam's main repo, fetch recent release branches:

    $ cd beam
$ git fetch origin
          
    Otherwise, make a clone of the main repo (not your fork of Beam), and add a remote for your fork:
    $ git clone https://github.com/apache/beam.git  
$ cd beam
$ git remote add ${GITHUB_USERNAME} git@github.com:${GITHUB_USERNAME}/beam.git

  3. In a local clone of a Beam repo, start a new branch. However, instead of basing your branch on top of master, branch off the release branch. For example:

    $ git checkout origin/release-2.56.0
$ git checkout -b cherrypick_pr_25000



    Find from Github UI the commit ID(s) of  your merged PR, that you need to cherry-pick. 

    For example, going to https://github.com/apache/beam/pull/25000, we can  find that the merge commit was e94aa456fc3ec9784a3aacddb03eb13b8e109785. Then, cherry-pick the commit in the new branch 


    $ git cherry-pick e94aa45


    If you see an error: commit <somehash> is a merge but no -m option was given  , it means that a committer merged your PR by creating a merge commit, instead of squashing and merging all commits into one at merge time. In this case, the merge commit has more than 1 parent. The first parent refers to the branch into which the merge has been completed. You can cherry-pick the merge commit by specifying the parent:   git cherry-pick dc6b72caf7 -m 1  or (a slightly better option that preserves commit history), by going to the list of the commits on your PR, https://github.com/apache/beam/pull/25000/commits, and running git cherry-pick  for each commit in the PR in the same order.     

    Alternatively, if you have an existing branch with your changes, and you are familiar with git rebase flow (or would like to learn it - it's very useful!), you can rebase your existing branch on top of Beam release branch, and drop   all commits except for the commits that you need to cherry-pick. To perform a rebase,  run:
          git pull --rebase=interactive origin release-2.56.0    


  4. Push the branch with cherry-picked commits to your fork: 

    $ git push ${GITHUB_USERNAME} cherrypick_pr_25000
  5. Go to github UI, and create a pull request from the branch on your fork. When selecting the Apache Beam base branch, select the correct release branch. 



    You might be able to use a link like https://github.com/apache/beam/compare/release-2.56.0...github_username:cherrypick_pr_25000 to get to the right page in the UI. Change your username and branch name appropriately.
  6. Name your PR to be clear that this is a cherry-pick, and reference the cherry-picked PR. For example: [release-2.56.0] Cherrypick PR #25000 to the release branch. For example: https://github.com/apache/beam/pull/31598
  7. Send your PR to the current Beam release manager for review.


  • No labels