Giving Back to Upstream: An open source beginner's primer is a talk presented at DockerCon 2019 in San Francisco on April 30, 2019. In this talk, Phil Estes presented his story of getting involved in the container open source ecosystem, and provides a set of "open source 101" tips and guidance for those wanting to participate in open source contribution.

1. Phil Estes
Distinguished Engineer
CTO, Architecture Strategy
IBM Cloud Platform
@estesp
Giving Back To
Upstream
An Open Source Beginner’s Primer

2. Phil Estes
Docker core engine maintainer (2015-..)
containerd maintainer (2016-..)
creator of bucketbench, manifest-tool
Many 100s of PRs created, reviewed, merged
About Me
@estesp

3. The Premise
@estesp
● 86% of enterprises using or increasing use of OSS
● 53% contribute back in some way
● 46% encourage contribution by employees

4. Open Source pre-101
@estesp
PERMISSION
OSS
PRINCIPLES
PASSION

5. Presentation Caveats
● Open Source ≠ GitHub
● OSS Contribution ≠ Coding
● YMMV - I can’t cover every situation/project
● IANAL - You must seek your own company’s
guidance regarding licenses, proprietary code, etc.
@estesp

6. GitHub
Almost every project you want to contribute to is here.
@estesp

7. GitHub, Git, What??
What’s the relationship between ‘git’ and ‘GitHub’?
git
GitHub
git is a source code management tool, written by Linus Torvalds, built as
a distributed version control system. The Linux kernel was the first
adopter, but it has become the defacto source control system today.
GitHub is a hosted source code management system built around the
git version control tooling. It is not simply “hosted git” but a series of
capabilities useful for distributed software development. Very popular
with open source projects, albeit not the only solution.
@estesp

8. GitHub User (Security) Basics
Use a strong password.
Please turn on 2-factor authentication in your account.
Add an ssh key to your account (for cmd line access).
Add a PGP key for commit signing to your account.
https://blog.mikesir87.io/2018/05/sign-your-commits-or-else/
@estesp

9. GitHub Basics
● Top Object: Personal account or Organization
● Orgs and Accounts contain Repositories
github.com/estesp github.com/docker
github.com/estesp/manifest-tool
github.com/estesp/bucketbench
github.com/docker/cli
github.com/docker/buildkit
@estesp

10. GitHub Guides https://guides.github.com
@estesp

11. GitHub: Ok, What Next?
● Contribute to an existing project:
● Create your own project:
@estesp

12. Cloning a Forked Repository
$ git clone git@github.com:estesp/mynewrepo
Cloning into 'mynewrepo'...
remote: Enumerating objects: 10, done.
remote: Counting objects: 100% (10/10), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 293 (delta 1), reused 5 (delta 1), pack-reused 283
Receiving objects: 100% (293/293), 178.62 KiB | 2.55 MiB/s, done.
Resolving deltas: 100% (115/115), done.
$ ls mynewrepo/
cni.go errors.go LICENSE namespace_opts.go README.md
testutils.go vendor cni_test.go helper.go namespace.go
opts.go result.go types.go vendor.conf
$ git remote add upstream https://github.com/myorg/mynewrepo
$ git remote -v
origin git@github.com:estesp/mynewrepo (fetch)
origin git@github.com:estesp/mynewrepo (push)
upstream https://github.com/myorg/mynewrepo (fetch)
@estesp

13. Open Source Project Processes
● Every project is unique. However, some basics:
○ Look for a CONTRIBUTING.md file
○ Read through the README.md
○ Is there a LICENSE file? If not, ask why!
○ How is the project governed? GOVERNANCE.md
○ Code of Conduct?
@estesp

14. Communication
Where does this community congregate?
Is there a weekly developer call or contributor’s call? Is
it recorded/posted so you can “catch up”?
Do they meet up on Slack/IRC or other messaging
platforms?
Do they have a mailing list where design, roadmaps,
and/or proposals and features are discussed?
@estesp

15. Finding Work To Do
● Every project should have labels targeted at first time contributors
○ Docker engine (moby/moby) uses exp/beginner (so does containerd)
○ Look back at the CONTRIBUTING.md documentation; first time guide?
○ Check out https://github.com/MunGell/awesome-for-beginners
@estesp

16. Anatomy of a Pull Request
UPSTREAM
GITHUB
PROJECT
FORK PERSONAL
GITHUB
FORK
BRANCH - EDIT FILE(S)
- `git add {files}`
- `git commit`
PERSONAL
GITHUB
FORK
PUSH
UPSTREAM
GITHUB
PROJECT
CREATE PR
{ ONE TIME ONLY }
@estesp

17. Common PR Activities
What happens if it isn’t an “easy merge”?
Changes are committed in the project’s main branch
that your PR must move on top of to properly be tested
Modifications are requested to your changes by
reviewers or maintainers in the project.
You did your work across many small commits but the
project requires approved PRs to be a single commit
REBASE
REPUSH
SQUASH
@estesp

18. Success and Failure Upstream
Remember maintainers/reviewers/committers are people too.
They have personal lives, bad days, work pressures, etc.
CLASHING
OPINIONS
REACHING
AN
IMPASSE
NO/SLOW
RESPONSE
YOU MAY DEAL WITH ONE OR MORE OF THESE ISSUES:
@estesp

19. Phil’s Tips for Success
● When you think you’ve been patient, be a little more patient
● Ask a non-invested (and trusted) party for their review/opinion
● Make life as easy as possible for maintainers/reviewers
○ Follow all the recommended steps for contributing in the repo
● Show you care as much about the project as you do your “changes”
○ Make the tests better, write some docs, clean up the contributor’s guide
○ Take time to add good descriptions, comments, reasons for changes
○ Be polite and helpful in communication
@estesp

20. Personal Projects
● Get permission (as required)
● Determine your model
● Make it easy to contribute
● Set good expectations
● Mark project status clearly
@estesp

21. Establishing an Open Source
Program Office
Lee Calcote, Layer5, CNCF
Tim Tyler, Met Life
Wednesday, May 1
12:00-12:40pm
Room 3020
@estesp

22. Open Source Summit:
Thursday!
containerd maintainers
Thursday, May 2
2:30-4:30pm
Room 2020
@estesp

23. Thank You!
@estesp