Chromium Contributing Explained: Writing Good Patches

1Samsung Open Source Group

Chromium Contribution Process Explained

a.k.a. Writing good patches

Adenilson CavalcantiMSc. BSc.

Samsung Open Source [email protected] (or

[email protected])


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.

Samsung Open Source Group


Create a Google Account

9Samsung Open Source Group *if a colleague has a checkout, use a pendrive to copy.

CheckoutInstall depot tools:

git clone https://chromium.googlecode.com/chromium/tools/depot_tools.git

Export PATH=$DEPOT_FOLDERCheckout 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


BuildBeefy hardware: 64 bits + 16GB ram.Intel [email protected] 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

Notify chromium

issues

2. Develop patch

7. Land patch

Retry 3xManual 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.

Samsung Open Source Group


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.

23

Extra Tips


Writing Good Commit LogsTo 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 LogsBad 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 happenedin 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

Software

Transcript of Chromium Contributing Explained: Writing Good Patches