Contributing to any open source project could be overwhelming at the beginning, given there are some no-writing rules on them. But there are some tricks which can facilitate you during the process. This session provides some etiquette rules that I've learned on my Open Source journey as contributor and reviewer from several projects. The main takeaway of this will give the participant a set of best practices during the on-boarding process in any open source project.
2. Victor Morales
• +18 yrs as a Software Engineer
• .NET, Java, python, Go programmer
• OpenStack, OPNFV, ONAP and CNCF
contributor.
https://about.me/electrocucaracha
3. One of the key elements in the Andean worldview, which is for
this purpose extremely relevant, is the principle of
reciprocity. It defines all types of social relations and is
based on a principle of interrelation and interdependency,
which thus suggests a form of mutual support and
consideration of all parts of society. Social norms, cultural
tradition and religious, mythic beliefs form one entity in Andean
cosmology. The underlying view is an holistic one, which sees
the human beings as parts of space (nature), time (history and
tradition) and of their current society (present social setting). In
this context, coca has a binding function as it
represents a mean of communication, among
the respective elements as well as between them.
Reciprocity
http://revelaaustria.com/el-significado-de-la-hoja-de-coca-para-el-indigena-de-los-andes/
https://core.ac.uk/reader/11592764
7. A short guide to facilitate the onboarding
process of potential project contributors.
It’s helpful for:
• Contributors who want to know items
they’re welcome to tackle
• Consumers who want to build off the
project
https://www.mysafetysign.com/read-user-manual-before-operating-notice-sign/sku-s-9120
Read
CONTRIBUTING.md
8. 1. Review your own code first
• Run Tests locally
• Ensure there is no typos
2. Narrowly scope changes
• No more than 300–400 lines of code
• Provide a good commit message
• Fill the PR information template
https://www.flickr.com/photos/18378305@N00/12623408743
Prior submission
9. • First line – Short summary (<50 chars)
• Informative body
• Brief description of the problem.
• Describe the functional change being made and
the result of it.
• Lines should be wrapped at 72 chars
• Issue/Bug reference
https://www.conventionalcommits.org/en/v1.0.0/#summary
https://google.github.io/eng-practices/review/developer/cl-descriptions.html
https://wiki.openstack.org/wiki/GitCommitMessages
https://docs.releng.linuxfoundation.org/en/latest/best-practices.html
Git Commit messages
10. 3. Respond graciously to critiques
• Don’t take it personally
• Be patient when your reviewer is
wrong
• Communicate your responses explicitly
4. Answer questions with the code
itself
5. Minimize lag between rounds of
review
• The code review has a higher priority
than the development task to avoid
long-lived pull requests.
• Avoid to leave unclear comments.
https://www.flickr.com/photos/7321654@N03/3456375365
Post-submission
12. “A software quality assurance activity
in which one or several people check
a program mainly by viewing and
reading parts of its source code, and
they do so after implementation or as
an interruption of implementation.” -
Wikipedia
https://www.flickr.com/photos/30478819@N08/45977680015
Definition
13. 1. Clearly understands the
acceptance criteria of the code.
• Reviews the code against the
code review checklist
(CONTRIBUTING.md)
2. Each commit should be
reviewed by at least one or two
team members before pushing
the code to the main branch.
https://www.flickr.com/photos/49968232@N00/13421955434
Who is a reviewer?
14. The best reviewer is the person who will be able to
give you the most thorough and correct review for
the piece of code you are writing. This usually means
the owner(s) of the code, who may or may not be
the people in the OWNERS file. Sometimes this
means asking different people to review different
parts of the CL.
Automation scripts need to run
successfully in order to pass review
https://www.flickr.com/photos/49503047029@N01/246595786
Choosing Reviewer
15. • Is the code well-designed and appropriate for your
system?
• Does the code behave as the author likely intended?
• Is the way the code behaves good for its users?
• Could the code be made simpler?
• Would another developer be able to easily understand
and use this code when they come across it in the
future?
• Does the code have correct and well-designed
automated tests?
• Did the developer choose clear names for variables,
classes, methods, etc.?
• Are the comments clear and useful?
• Does the code follow our style guides?
• Did the developer also update relevant documentation?
https://www.flickr.com/photos/66757486@N00/2380987996
Reviewer’s considerations
16. Reviewer (cont.)
4. Automate the easy stuff (linting, spelling, labeling, etc.)
• Linting (Hard-Coded Values. Often indicate hasty
development) - https://github.com/github/super-linter
• Spelling (Typos and Bad Formatting. Reflect carelessness,
cause frustration, and damage reputation) -
https://github.com/reviewdog/action-misspell
https://pypi.org/project/pyspelling/
• Triage - https://github.com/actions/labeler
https://docs.pullapprove.com/
• Test Coverage threshold.
https://coverage.readthedocs.io/en/coverage-
5.5/cmd.html?highlight=--fail-under#reporting
https://www.flickr.com/photos/78205255@N00/96887547
17. The golden rule: Time is money
• Reviewer’s time
• Contributor’s time
• CI’s time
https://www.flickr.com/photos/38451115@N04/3992935923
Contributing to any open source project could be overwhelming at the beginning, given there are some no-writing rules on them. But there are some tricks which can facilitate you during the process. This session provides some etiquette rules that I've learned on my Open Source journey as contributor and reviewer from several projects. The main takeaway of this will give the participant a set of best practices during the on-boarding process in any open source project.
https://mtlynch.io/code-review-love/
https://mtlynch.io/code-review-love/
https://google.github.io/eng-practices/review/
We found no evidence for the delayed issue effect; i.e.the effort to resolve issues in a later phase was not consistently or substantially greater thanwhen issues were resolved soon after their introduction. https://arxiv.org/pdf/1609.04886.pdf
The best reviewer is the person who will be able to give you the most thorough and correct review for the piece of code you are writing. This usually means the owner(s) of the code, who may or may not be the people in the OWNERS file. Sometimes this means asking different people to review different parts of the CL.