Chromium Contributing Explained: Writing Good Patches

1Samsung Open Source Group
Chromium Contribution Process
Explained
a.k.a. Writing good patches
Adenilson Cavalcanti
MSc. BSc.
Samsung Open Source Group
a.cavalcanti@samsung.com (or
cavalcantii@chromium.org)

About the instructor
Adenilson Cavalcanti (a.k.a. Savago)

WebKit & Blink committer.

W3C CSS WG member.

Servo contributor.

15 years of C++.

13 years of Linux/OSS experience.

8 years of mobile.

4 years of WebKit.

2 years of Blink.

Why Are We Here?

Share some lessons learned while contributing
to Blink (and other open source projects).

Start the discussion about good practices.

Explain some cultural aspects of the Chromium
community.

Present tips and tricks of the trade.

Presentation Structure

Chromium contribution workflow explained.

5 Principles to make good contributions.

Tips.

Best practices working with Chromium team.

5
Blink Contribution Workflow
Explained

The Workflow in a Nutshell

Associate your @company email to a Google
account.

Checkout and build.

Implement a change.

Create a branch.

Run the tests.

Push to remote.

Kick the bots (or ask someone to do it).

Ask for review.

7
Create a Google Account
• Visit: https://accounts.google.com/SignUp
• Use your @company.com account.
• You will receive the validation link through your
email.
• The password can (and should) be different.

Create a Google Account

9Samsung Open Source Group *if a colleague has a checkout, use a pendrive to copy.
Checkout

Install depot tools:

git clone
https://chromium.googlecode.com/chromium/tools/depot_tools.
git

Export PATH=$DEPOT_FOLDER

Checkout the code* (21GB)

mkdir chromium; cd chromium; fetch –nohooks chromium;
gclient runhooks

Update: git checkout master; git rebase-update; gclient sync
--jobs=16

Further info: http://dev.chromium.org/developers/how-tos/get-
the-code

Build

Beefy hardware: 64 bits + 16GB ram.

Intel i7@2.5Ghz takes 45 minutes.

Uses +30GB of disk space.

Building*:

./build/gyp_chromium –Dwerror= #configure

ninja -C out/Debug/ blink_tests -j10 #layout tests

ninja -C out/Debug/ content_unittests -j10 #content

Targets: unit_tests | browser_tests | net_unittests |
gpu_unittests

ninja -C out/Debug chrome -j10 #chromium browser

Patching

Make a change, create a branch and commit:

git checkout –b myFeature

git commit -a -m “It does something.”

Running Tests + Upload

Layout tests:

./Tools/Scripts/run-webkit-tests --debug css3/filters

Content tests:

./out/Debug/content_unittests | unit_tests

If everything is ok (i.e. no regressions), upload
the patch:

git cl upload

Kick the bots:

git cl try

13
N
otify
chrom
ium
issues
2. Develop patch
7. Land patch
Retry 3x
Manual commit
Submitting Patches: Blink

Watching the Bots

You should receive emails about bot status.

Investigate if a bot is red.

Blink/Chromium: Gaining Status
Committer:
• Same as WebKit (30~40 non-trivial patches).
• Bonus if already a WebKit committer.
Owner:
• Have provided high quality reviews / design feedback.
• Be a Chromium project member for at least 6 months.
• Have submitted a substantial number of non-trivial changes.
• Had made changes to the affected directory within 90 days.
• Bandwidth to contribute with other owners.

16
5 Principles To Make Good
Contributions

The Magic Secret to a Good Patch

Answer these 5 questions.

The 5 Magical Questions

Does it improve performance?

Is it an enabler for others?

Is it spec compliant?

Is it innovative?

Does it fit the project architecture?

If Everything Fails…

Does it improve the performance?

Is it an enabler for others?

Is it spec compliant?

Is it innovative?

Does it fit the project architecture?
DOES IT AT LEAST CLEAN UP THE CODE
REMARKABLY?

20
If the Answer is No…
Give up and try something different.

Final Consideration

Submit something you are proud of.

Put yourself in the reviewer’s shoes.

Final Consideration

Submit something you are proud of.

Put yourself in the reviewer’s shoes.
Remember: you are putting your name on
the line in addition to our company image.

Writing Good Commit Logs

To be useful, a log must foremost describe why
a change was made (the what is obvious by
reading the code).

Programmer types:

poor programmers don’t write logs;

good programmers write logs that need the code to be
understood;

great programmers write logs that are self explanatory
and may include references to external
documentation.

Writing Good Commit Logs

Bad log: “fix bug and refactor.”

Good log example:

Commits Must Be Atomic

Do one change (e.g. implementing one feature)
and resist the urge to add non-related things
(e.g. aesthetics, typos, etc).

If you identified something else, open a new bug
to track the issue and submit another patch later.

Quality X Quantity

3 good patches are much better than 15 obvious
ones.

1 Ferrari F12 == 16 Fiat 500.
Quality X Quantity

Self-Review Your Code

When you are done, look for possible areas for
improvement.

Try to find cases where it would fail.

Does it scale up? Does it scale down?

Know Thy Browser

Have all browsers handy and know their
behavior for what you working on.

Know the Code Style

Before starting anything, read:

https://www.chromium.org/developers/coding-style

https://www.chromium.org/blink/coding-style

Fix the mistakes pointed by ‘git cl upload’.

32
Best Practices Working with
Chromium Team

Communication is King

Think twice and formulate your thoughts in an
articulated way.

If you have difficulties with English, prefer async
comm (e.g. mailing list).

Go straight to the point, time is valuable.

The way you speak may affect how reviewers
may perceive your ideas.
When using IRC:

How to Ask Smart Questions*

Do your homework:

research;

read available documentation;

ask your team members;

Write the question with a clear title.

Proof read before posting.

Add links to each relevant info you found (to
prove that at least you tried to find answers).
*Reference: http://catb.org/~esr/faqs/smart-questions.html

Know the Time Zones

The team is distributed (from Korea):

California is 16 hours behind.

Europe (UK) is 8 hours behind.

Sometimes you will have to wake up earlier (or
wait for late night) to reach the right person.

Observe Cultural Differences

Code review is straight and to the point.

The criticism is directed at the code, not at you
as a person.

Any accepted contribution brings a cost for
maintenance and has to be within the high
standards of the project.

Observe Cultural Differences

USA: it is alright, OK.

Russia: zero.

Brazil: insult!

Choose an Area and a Reviewer

Select an area/subsystem to work on.

Develop a relationship with one or two
reviewers.

Avoid jumping from one area to another as it will
impact your productivity and your potential
nomination to become a committer in the future.

Use Bots Sparingly

Bots consume resources and many queued jobs
slows down every single contributor.

Only select 3 or 4 bots (e.g. mac, windows,
android, linux-debug) and submit the job if you
have tested it locally.

Recently a developer was almost had bot
permissions blocked because he was ‘trigger
happy’.

When to Duck

Generally, the reviewers are right when they ask
for changes.

Be grateful for the feedback and implement all
changes.

Don’t push back or stall (especially if you are not
used to the subsystem you are working).

Again: the reviewers are doing you a favor by
reviewing your patch.

When to Hold Your Ground

If you truly believe your idea makes sense and
have done great research.

If you have data (e.g. benchmarks).

When you can point to specs (W3C, WHATWG).

When other browsers implement the same
behavior.

The Job is Never Completed

After a patch has landed, keep watching the bots
for any regressions:

http://build.chromium.org/p/chromium/waterfall

If you noticed that your patch is responsible for a
regression, ping the reviewer in IRC and discuss
what to do next.

Check Your Email on the Weekends*

It may happen that your contribution triggered a
regression and in such case you will be notified
by email.

Promptly answer the email and start
investigating.

If not possible, suggest to rollback the patch and
explain when you can start looking into the
subject.
*if you can’t, time your patches with
weekdays (e.g. Tuesday/Wednesday).

Check Your Email on the
Weekends
This happened
in a Friday at 23hs!

Follow the Mailing List

Be aware of what is happening in the project as
a whole.

Sign in to blink-dev and chromium-dev.

Before starting something bigger, ask reviewers
what they think about it.

Questions and Answers

Thank You!

Chromium Contributing Explained: Writing Good Patches

Recommended

Recommended

More Related Content

Viewers also liked

Viewers also liked (18)

Similar to Chromium Contributing Explained: Writing Good Patches

Similar to Chromium Contributing Explained: Writing Good Patches (20)

More from Samsung Open Source Group

More from Samsung Open Source Group (20)

Recently uploaded

Recently uploaded (20)

Chromium Contributing Explained: Writing Good Patches