GitHub Workflow

This document helps you get started using GitHub for Istio. Below, we outline one of the more common Git workflows that core developers use, although other workflows are also valid.

• Fork a repository
• Clone your fork
• Enable pre commit hook
• Create a branch and make changes
• Keeping your fork in sync
• Committing changes to your fork
• Creating a pull request
• Branching strategy
• Getting a code review
• When to retain commits and when to squash
• Using Github Projects

Fork a repository

1. Go to https://github.com/istio and select a repository. The rest of this document assumes you're forking the main istio repo.
2. Click the "Fork" button (at the top right)

Clone your fork

The commands below require that you have $GOPATH set ($GOPATH docs). We highly recommend you put Istio's code into your GOPATH. Note: the commands below will not work if there is more than one directory in your $GOPATH.

cd $ISTIO
git clone https://github.com/$GITHUB_USER/istio
cd istio
git remote add upstream 'https://github.com/istio/istio'
git config --global --add http.followRedirects 1

Enable pre-commit hook

NOTE: The precommit hook is not functional as of 11/08/2017 following the repo reorganization. It should come back alive shortly.

Istio uses a local pre-commit hook to ensure that the code passes local tests before being committed.

Run

./bin/pre-commit
Installing pre-commit hook

This hook is invoked every time you commit changes locally. The commit is allowed to proceed only if the hook succeeds.

Create a branch and make changes

git checkout -b my-feature
# Make your code changes

Keeping your fork in sync

git fetch upstream
git rebase upstream/master

Note: If you have write access to the main repositories (e.g. github.com/istio/istio), you should modify your Git configuration so that you can't accidentally push to upstream:

git remote set-url --push upstream no_push

Committing changes to your fork

When you're happy with some changes, you can commit them to your repo:

git add .
git commit

Then push the change to your fork (typically called origin). When prompted for authentication, use your GitHub username as usual but the personal access token as your password if you have not setup ssh keys. Please follow these instructions if you want to cache the token.

git push origin my-feature

Creating a pull request

1. Visit https://github.com/$GITHUB_USER/istio if you created a fork in your own github repository, or https://github.com/istio/istio and navigate to your branch (e.g. "my-feature").
2. Click the "Compare" button to compare the change, and then the "Pull request" button next to your "my-feature" branch.

Branching strategy

For each release, a branch will be created to lock down changes to the release. For example, the 1.2.x releases will be built from the release-1.2 branch.

All pull requests should be sent to master first. Once merged, it can be cherry-picked to the release branch if required. This can be done automatically by adding the appropriate cherrypick/release-1.X label to the PR.

Changes to the release branch must be approved by the release managers for the release. Generally, only bug fixes are accepted.

Getting a code review

Once your pull request has been opened it will be assigned to one or more reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style.

Very small PRs are easy to review. Very large PRs are very difficult to review. GitHub has a built-in code review tool, which is what most people use.

When to retain commits and when to squash

Upon merge, all Git commits should represent meaningful milestones or units of work. Use commits to add clarity to the development and review process.

Before merging a PR, squash any "fix review feedback", "typo", and "rebased" sorts of commits. It is not imperative that every commit in a PR compile and pass tests independently, but it is worth striving for. For mass automated fixups (e.g. automated doc formatting), use one or more commits for the changes to tooling and a final commit to apply the fixup en masse. This makes reviews much easier.

Please do not use force push after submitting a PR to resolve review feedback. Doing so results in an inability to see what has changed between revisions of the PR. Instead submit additional commits until the PR is suitable for merging. Once the PR is suitable for merging, the commits will be squashed to simplify the commit.

Using Github Projects

Issue priorities are managed by the Prioritization GitHub project.

Issue priority can be set by:

• Dragging cards on the project board to modify issues already prioritized.
• Selecting "Add cards" will list all issues not currently prioritized, which can then be dragged into the appropriate column. This can be filtered by standard GitHub queries, such as is:open is:issue label:"area/test and release"
• From an issue directly. Under "Projects", add it to the Prioritization project, then assign it a priority.