README.chromium

Name: gRPC, an RPC library and framework
Short Name: gRPC
URL: https://github.com/grpc/grpc
License: BSD-style, copyright Google
License File: LICENSE
Revision: 1bc2976a0f51e14d3525aecbf4b3450445ed2d1b
Security Critical: yes

This directory contains Chrome's version of the C-version of the gRPC
library.

Updating BUILD.gn:

The BUILD.gn file is autogenerated from template/BUILD.gn.template file. To
regenerate it, run tools/buildgen/generate_projects.sh . Since it's not always
done for every upstream commit, this command is likely to regenerate also many
build files. Don't commit those changes -- they will only result in conflicts
once upstream updates them.

Rolling DEPS:

third_party/grpc is a Git repository separate from main Chromium repository. The
contents of third_party/grpc directory of your Chromium checkout are managed by
the gclient tool. It determines the version to checkout by looking at src/DEPS
file.

To update third_party/grpc you need to first make sure a proper version exists
in the repository, and then edit the DEPS file to point to a proper commit.

There are two possible ways in which one would like to update gRPC: merge
upstream changes, and make new local changes.

Merging upstream changes:

To merge upstream changes, one needs to rebase our local changes on top of
upstream changes. We cannot just rebase it on top of master, and force push to
the same branch, as this will result in the commit that is currently HEAD of
that branch (and as such pointed to by DEPS file) to get garbage collected. We
need to create a new branch with the rebase.

Suppose origin/chromium-deps/2016-07-27 is the remote branch with our most
recent local changes (to confirm this, do `git branch -r`, and check whether top
commit of branch with newest date matches the commit id in src/DEPS). The
process is as follows:

xyzzyz@xyzzyz:/tmp/grpc$ git checkout origin/chromium-deps/2016-07-27
Note: checking out 'origin/chromium-deps/2016-07-27'.

You are in 'detached HEAD' state. (...)

HEAD is now at 3334ae7... Update gRPC's BUILD.gn template to fix the public_configs, and targets dependencies.

xyzzyz@xyzzyz:/tmp/grpc$ git checkout -b 2016-08-17
Switched to a new branch '2016-08-17

# Master branch is mirroring upstream changes, and doesn't include our local
# commits.
xyzzyz@xyzzyz:/tmp/grpc$ git rebase master
First, rewinding head to replay your work on top of it...
Applying: Add codereview.settings and README.chromium to gRPC
Applying: Add OWNERS, update README.chromium in Chromium's gRPC repo.
Applying: Add BUILD.gn to third_party/gRPC
Applying: Update BUILD.gn after recent gRPC roll.
Applying: Generate BUILD.gn from template
Applying: Update gRPC's BUILD.gn template to fix the public_configs, and targets dependencies.

xyzzyz@xyzzyz:/tmp/grpc$ git push -u origin HEAD:refs/heads/chromium-deps/2016-08-17 
Counting objects: 25, done.
Delta compression using up to 48 threads.
Compressing objects: 100% (22/22), done.
Writing objects: 100% (25/25), 18.71 KiB | 0 bytes/s, done.
Total 25 (delta 10), reused 11 (delta 2)
remote: Resolving deltas: 100% (10/10)
remote: Processing changes: done    
remote: (W) 4d49641: commit subject >65 characters; use shorter first paragraph
To https://chromium.googlesource.com/external/github.com/grpc/grpc
 * [new branch]      HEAD -> chromium-deps/2016-08-17
Branch 2016-08-17 set up to track remote branch chromium-deps/2016-08-17 from origin.

xyzzyz@xyzzyz:/tmp/grpc$ git log | head
commit 4d496419f70a70df0fb99753cdcfd168aa5b5053


Now the most recent remote branch is origin/chromium-deps/2016-08-17. What
remains is to edit chromium/src/DEPS file to point to the commit
4d496419f70a70df0fb99753cdcfd168aa5b5053, create a Chromium CL, send it to
review and land using Chromium CQ.

If any conflicts arise during rebase, one should resolve them before pushing to
new remote branch.

Creating new local changes:

Since new local changes only add new commits on top of existing ones, we don't
have to create a new branch, as old commits are still reachable through the new
HEAD, and thus won't get garbage collected.

Suppose origin/chromium-deps/2016-08-17 is the remote branch with our most
recent local changes. The process is the following:

xyzzyz@xyzzyz:/tmp/grpc$ git checkout origin/chromium-deps/2016-08-17
Note: checking out 'origin/chromium-deps/2016-08-17'.

You are in 'detached HEAD' state. (...)

HEAD is now at 4d49641... Update gRPC's BUILD.gn template to fix the public_configs, and targets dependencies.

xyzzyz@xyzzyz:/tmp/grpc$ git checkout -b my_new_local_changes
Switched to a new branch 'my_new_local_changes'

# This is very important step to ensure the Code Review tool knows on top of
# which remote branch to take a diff and land the change.
xyzzyz@xyzzyz:/tmp/grpc$ git branch --set-upstream-to origin/chromium-deps/2016-08-17
Branch my_new_local_changes set up to track remote branch chromium-deps/2016-08-17 from origin.

xyzzyz@xyzzyz:/tmp/grpc$ emacsclient README.chromium
... make changes ...

xyzzyz@xyzzyz:/tmp/grpc$ git add README.chromium && git commit -m "Update README.chromium"

xyzzyz@xyzzyz:/tmp/grpc$ git cl upload
... send to code review, and once LGTM is obtained...

xyzzyz@xyzzyz:/tmp/grpc$ git cl land

After landing the change, you can edit the chromium/src/DEPS file to point to
the commit id of this change, commit, create a Chromium CL and land it using the
usual process.