Xen Project Contributor Training - Part 1 introduction v1.0
-
Upload
the-linux-foundation -
Category
Documents
-
view
4.020 -
download
1
Transcript of Xen Project Contributor Training - Part 1 introduction v1.0
![Page 1: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/1.jpg)
Lars Kurth Community Manager, Xen Project Chairman, Xen Project Advisory Board Director, Open Source Business Office, Citrix
lars_kurth
![Page 2: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/2.jpg)
Culture, Roles, Community
Goals
Good Planning & Preparation
Following workflow and conventions
Systematic approach
Good Communicati
on
Unnecessary iterations, misunderstandings and wasted time of contributor and reviewers time
Wrong expectations leading to frustration and conflict
![Page 3: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/3.jpg)
Goal: Effective Contributions Factors that impact Effectiveness
Motivators of Community Stakeholders Common factors for disagreement when trying to contribute
The case for Code Reviews: Find bugs early & often Factors impacting Review Duration
Jumbled Reviews and Phasing Code Reviews: Theory
Relevant Conventions and Processes in the Xen Project Systematic approach to acting on Feedback
Communication is key : Avoid Misunderstandings
![Page 4: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/4.jpg)
Enable you to Work Efficiently with the Xen Project Developer Community
Vinovyn @ Flickr
![Page 5: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/5.jpg)
Which factors impact the length of time it takes your patch to be up-streamed?
![Page 6: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/6.jpg)
• Get your code into the code line
• Get it in as quickly as possible, with as little re-work as possible • Or at least, make the process of contributing predictable
• You may be under pressure from a (product) manager
Enabling feature or API which you want to be widely used
Feature or API, that you are using in your product or service. In other words you don’t care much if someone else uses it
Research purpose
![Page 7: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/7.jpg)
Up to 1 week 1 to 2 weeks 2 to 3 weeks 3 to 6 weeks 6 to 13 weeks More than 13 weeks
43%
15%
10% 13%
11% 8%
As a contributor, most of the time you want to get your code reviewed and accepted as quickly as possible, with as few modifications as possible
![Page 8: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/8.jpg)
Reviewers, Maintainers, Committers, Project Lead
• System Properties: Code readability, understanding what goes in, maintainability, quality, performance, scalability, …
• Practical Issues: – Is this patch one I have to look at? – Reviewer / maintainer of the patch series – Archaeologist: years down the line – why is the code as it is?
• Workload and personal: – Wants to avoid un-necessary workload – Day-job: aka other commitments – Has a personal communication style – Reputation within the community
![Page 9: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/9.jpg)
30% Community Growth p.a.
Contributors competing for review time from stretched maintainer / reviewer base
Average review time up from 28 to 32 days in 6 months
Problem
![Page 10: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/10.jpg)
Up to 1 week 1 to 2 weeks 2 to 3 weeks 3 to 6 weeks 6 to 13 weeks More than 13 weeks
43%
15%
10% 13%
11% 8%
Gatekeepers ideally want code to go in quickly
BUT: they also have many other factors to consider
![Page 11: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/11.jpg)
Gatekeeper Contributor
Different mindset Different expectations
Bad communication Misunderstandings
Usually common interest Process, convention & tools
Awareness, Mindset / Empathy, Planning, Good Communication, Trust / Respect, etc.
![Page 12: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/12.jpg)
The tension identified is not specific to OSS development, but is a property of Code Review
Aka the tension between submitter and gatekeeper (reviewer)
Vinovyn @ Flickr
![Page 13: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/13.jpg)
Culture, Roles, Community
Goals
Good Planning & Preparation
Following workflow and conventions
Systematic approach
Good Communicati
on
![Page 14: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/14.jpg)
The case for Peer Code Review Find Bugs Early and Often
![Page 15: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/15.jpg)
One of our customers set out to test exactly how much money the company would have saved had they used peer review in a certain three-month, 10,000-line project with 10 developers. They tracked how many bugs were found by QA and customers in the subsequent six months. Then they went back and had another group of developers peer-review the code in question. Using metrics from previous releases of this project they knew the average cost of fixing a defect at each phase of development, so they were able to measure directly how much money they would have saved.
http://smartbear.com/smartbear/media/pdfs/ best-kept-secrets-of-peer-code-review.pdf
![Page 16: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/16.jpg)
![Page 17: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/17.jpg)
snoopsmouse @ Flickr
![Page 18: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/18.jpg)
• Projects don’t normally have a QA team è Bugs discovered later è even more expensive to fix
• Customer (user) discovered bugs are usually found in derivatives è time-lag and thus cost to fix is even more expensive
• Bugs in FOSS projects are often not fixed
• Bugs and bad quality can damage the reputation of a project
• And by extension they can damage the business interests and reputation of contributors to that project (including your own)
• Asking maintainers to take your patch in without good review = Asking others to fix bugs and carry significant cost for you in future
![Page 19: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/19.jpg)
Culture, Roles, Community
Goals
Good Planning & Preparation
Following workflow and conventions
Systematic approach
Good Communicati
on
![Page 20: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/20.jpg)
• Type of feature – Useful to many stake-holders or just to a single vendor? – Is the use-case explained or understood? – Do reviewers have all the information they need to be able to review?
• Complexity and Modularity – How many files and lines per patch? – How many components (hypervisor, qemu, toolstack, APIs, …)? – Does the structure of the patch/patch series help a review? – Do you need a design?
• Readability – Is it easy to infer the design from the patch? – Do you follow Coding standards? – Are complex code snippets explained within comments in the patch?
# of Iterations
Each question may require a
re-submit
![Page 21: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/21.jpg)
• Code Quality
• Test failures, Coverity Scan, … – Will Coverity Scan throw up issues? – Do you need new Test Cases? – Should you include tests upfront?
• Time and Experience – Delays may require rebasing the patch! – How responsive are you to reviewer comments? – How responsive is the reviewer? He/she may have a queue of requests! – Use past submission experience to estimate # of iterations – Your standing in the community (your track record)
• Other factors – Some patches may require documentation (e.g. API docs)
# of Iterations
Mission Creep (e.g. additional requirements to
minimize risk)
Elapsed time per iteration adding up
![Page 22: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/22.jpg)
Reviewer takes pity on contributor Gives some feedback (e.g. coding style, …) May ask some questions about the use-case and/or the design
Later it becomes clear that there is an issue with the use-case, design, architecture or assumptions
Significant re-work Extra effort for contributor and reviewer At this stage both may be somewhat annoyed (and we will get communication issues)
…
![Page 23: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/23.jpg)
Why do “jumbled” reviews happen?
![Page 24: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/24.jpg)
• Missing Information
• Wrongly set expectations due to misunderstandings • The reviewer giving too detailed information before agreeing that he is
happy with the use-case, architecture, design – and thus setting wrong expectations
• Another reviewer getting involved later down the road – There is also then potential for disagreement
![Page 25: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/25.jpg)
![Page 26: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/26.jpg)
Rationale (more if controversial)
Use Case
Context (Additional Information)
Design (if complex)
Assumptions (that you made)
Code & Code Review
Systematic approach to acting on Feedback
Dealing with test issues
![Page 27: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/27.jpg)
![Page 28: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/28.jpg)
• The Xen Project does not have a design requirement, but … – Designs are welcome, when it makes sense – When unsure, whether a design helps, ask: Outline the use-case, problem and approach you are planning to take. – Design discussions labeled “Design” + some version number + some text
• Requests For Comments (RFCs) – For use-cases, prototypes, proof of concepts, etc. – Ask reviewers specific questions about, use-case, architecture, design, etc. & look at specific issues you want feedback on
• Timing – Design or related questions best at beginning of release cycle – Make sure you understand and engage with the Release and Roadmap Process
• Communication – Prompt reviewers: Do you agree with Y (e.g. the design), given X (e.g. that I got some detailed feedback on the code, but also
some design related questions)? – The community is open to meetings in some cases (e.g. IRC meetings, calls, etc.) : high velocity communication can be more
effective than mail. • BUT: it only works, if the key stake-holders agree to attend. • AND: document agreements / disagreements / open questions post the meeting by posting a summary to the list, such that there is a
record
{MORE LATER}
![Page 29: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/29.jpg)
Interesting Facts about Code Reviews
In May of 2006 Cisco Systems performed a 10 month study of code reviews encompassing 2500 reviews of 3.2 million lines of code written by 50 developers.
This is the largest case study ever done on what’s known as a “lightweight” code review process.
![Page 30: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/30.jpg)
• Reviewers become ineffective when reviewing code for more than an hour at a time è Thus, a patch should be reviewable in < 1 hour
• Reviewers are most effective at reviewing small amounts of code. – Anything below 200 lines produces a high rate of defects, several times the
average è Thus, a patch should ideally be < 200 LOC and not larger than 400 – After that the results trail off considerably; no review larger than 250 lines
produced more than 37 defects per 1000 lines of code
• Reviews with author preparation (annotations explaining changes) have significantly smaller defect densities compared to reviews without è Incidentally that helps the reviewer also
![Page 31: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/31.jpg)
• The “Ego Effect”: Developers whose code is being reviewed immediately develop code with fewer defects in them
• Systematic Personal Growth: Developers who systematically address issues raised and make notes of classes of issues found, learn from their mistakes and from feedback and become better developers through self-awareness
• Hurt Feelings: Taking criticism (in particular in public) isn’t easy. The point of code review is to find issues. Hurt feelings are in most cases, the consequence of miscommunication and/or misunderstandings and not intentional è Which is why we will look at communication techniques later
![Page 32: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/32.jpg)
Culture, Roles, Community
Goals
Good Planning & Preparation
Following workflow and conventions
Systematic approach
Good Communicati
on
![Page 33: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/33.jpg)
![Page 34: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/34.jpg)
Preparation:
Contributor gathers changes
Contributor sends patch or patch series with meta-information (use case, rationale, design background, refs, …) to the mailing list
Inspection / Review:
Reviewer(s) examines code diffs following their own schedule and time constraints
Debate until resolved (Maintainer ACK)
Contributor keeps the process going (“Next revision”, “Are we done yet?”)
Rework:
Contributor responds to issues by making changes and sends new patch
Acked-by: <Maintainer>
Release Manager can object
Staging:
Committer checks changes into staging branch
Test suite passes / fails; Coverity Scan issues
Review Feedback
Reviewed-by Tested-by …
Test or scan fail
Complete: Change moved into master branch
No issue
![Page 35: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/35.jpg)
From Xen Project Governance
• Principles: Openness, Transparency, Meritocracy • Roles: Maintainers, Committers, Project Lead
• Conflict Resolution : Refereeing • Contribution Guidelines: Developer Certificate of Origin
• Security Vulnerability Policy (relevant for Coverity Scan)
![Page 36: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/36.jpg)
Documented and regularly used undocumented conventions (however changes to these are made only in line with governance) • Patch contribution workflow • Sign off (Acked-by, reviewed-by, etc.)
• Coding style
• Release Manager Role and Release Process (aka different stages)
• Access to Coverity Scan
• Staging-to-master pushgate and automated testing
• Personal repos hosted by Xen Project
• Design reviews (informal)
• Hackathons, Developer meetings, Ad-hoc meetings to resolve issues (informal)
![Page 37: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/37.jpg)
Culture, Roles, Community
Goals
Good Planning & Preparation
Following workflow and conventions
Systematic approach
Good Communicati
on
![Page 38: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/38.jpg)
![Page 39: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/39.jpg)
• Feedback comes in hierarchical threads
• Not always from one person • Feedback is not received in a linear list over time
• Needs to fit your working style and personal preference – Otherwise you will get tired of it and won’t use it
• Usually, it comes down to having one master list of issues somewhere – Otherwise you will “loose” or not act on bits of feedback
![Page 40: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/40.jpg)
How do you keep track of feedback from an email based code review?
Thomas Galvez @ Flickr
![Page 41: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/41.jpg)
Culture, Roles, Community
Goals
Good Planning & Preparation
Following workflow and conventions
Systematic approach
Good Communicati
on
![Page 42: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/42.jpg)
You have 30 seconds to write down terms you associate with “scalability”
Thomas Galvez @ Flickr
![Page 43: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/43.jpg)
Blinking Words are words or phrases that take on many possible interpretations, and where definitions blink between different meanings depending upon who hears it.
Note that the reason for the exercise is to show, how people with similar background can interpret terminology that is commonly used in their field very differently.
![Page 44: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/44.jpg)
Adversarial Style: Two ideas enter, one idea leaves
Collaborative Style: Participants build off of each others’ ideas, working together to create something new
• Education systems across the world have often a bias towards adversarial communication
• The goal for code reviews (and patch reviews) is inherently collaborative • BUT: often become Adversarial
![Page 45: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/45.jpg)
Or Techniques to Debug a Conversation
• High Quality Explanation • High Quality Inquiry
• The Left Hand Column (what was said and what you were thinking) • The Ladder (a cognitive process on how humans draw conclusions)
More Later
![Page 46: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/46.jpg)
Culture, Roles, Community
Goals
Good Planning & Preparation
Following workflow and conventions
Systematic approach
Good Communicati
on
![Page 47: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/47.jpg)
Awareness of Culture and others’ Perspective
Good Planning and Preparation
Following the Process and Conventions
Systematic approach to acting on Feedback
Good Communication
![Page 48: Xen Project Contributor Training - Part 1 introduction v1.0](https://reader033.fdocuments.in/reader033/viewer/2022060123/559707851a28ab9f2f8b4613/html5/thumbnails/48.jpg)
More Later
Part 2: Xen Project Processes, Conventions and Governance
Part 3: Communication – or avoiding misunderstandings