moar quality! moar inclusivity!€¦ · - debugging tips. @bobcatwilson. @bobcatwilson....
TRANSCRIPT
![Page 1: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/1.jpg)
@bobcatwilson
Write Better DocsMoar inclusivity!
Moar quality!Open Source Summit 2018
![Page 2: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/2.jpg)
@bobcatwilson
Hi!I’m Christie Wilson!Engineer @ Google
Container Tools Team
![Page 3: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/3.jpg)
@bobcatwilson
The Open Source Dream
![Page 4: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/4.jpg)
@bobcatwilson
Github 2017 stats
![Page 5: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/5.jpg)
@bobcatwilson
The Open Source Dream
![Page 6: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/6.jpg)
@bobcatwilson
The Open Source Dream
![Page 7: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/7.jpg)
@bobcatwilson
Docs for Developers
![Page 8: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/8.jpg)
@bobcatwilson
![Page 9: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/9.jpg)
@bobcatwilson
1. Issues2. CONTRIBUTING.md
+ DEVELOPMENT.md
3. A surprise!
![Page 10: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/10.jpg)
@bobcatwilson
Issues
![Page 11: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/11.jpg)
@bobcatwilson
Contributing: finding an issue
![Page 12: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/12.jpg)
@bobcatwilson
?
![Page 13: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/13.jpg)
@bobcatwilson
:(
![Page 14: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/14.jpg)
@bobcatwilson
Example of a good issue
github.com/knative/serving/issues/1859
![Page 15: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/15.jpg)
@bobcatwilson
![Page 16: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/16.jpg)
@bobcatwilson
Talking with maintainers
![Page 17: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/17.jpg)
@bobcatwilson
The 3 keys to great issues!
● Observed behaviour○ Links to the relevant code○ Snippets
● Expected behaviour● Steps to repro
○ Environment○ Commands
Screenshots, images, links
![Page 18: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/18.jpg)
@bobcatwilson
Github features● Use an issue template
![Page 19: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/19.jpg)
@bobcatwilson
Github features● Use labels!
○ good-first-issue○ help-wanted
![Page 20: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/20.jpg)
@bobcatwilson
How does Jaz get started on the issue?● Needs to know how to run tests● Your lib also runs as a service, needs to be
able to run it● Needs to know how the pull request workflow
works
![Page 21: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/21.jpg)
@bobcatwilson
![Page 22: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/22.jpg)
@bobcatwilson
1. Issues2. CONTRIBUTING.md +
DEVELOPMENT.md3. A surprise!
![Page 23: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/23.jpg)
@bobcatwilson
CONTRIBUTING.mdand
DEVELOPMENT.md
![Page 24: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/24.jpg)
@bobcatwilson
![Page 25: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/25.jpg)
@bobcatwilson
CONTRIBUTING.md DEVELOPMENT.md
Standard recognized by GitHub (e.g., integrated into PRs)
Extends CONTRIBUTING.md
(less standard)
![Page 26: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/26.jpg)
@bobcatwilson
CONTRIBUTING.md DEVELOPMENT.md
HOW to contribute to your repo.
Examples:- PR process- Issue requirements- Commit message style
WHAT a maintainer/contributor does.
Examples:- Build steps- Running tests- Debugging tips
![Page 27: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/27.jpg)
@bobcatwilson
![Page 28: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/28.jpg)
@bobcatwilson
![Page 29: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/29.jpg)
@bobcatwilson
![Page 30: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/30.jpg)
@bobcatwilson
How to write a great CONTRIBUTING.md● Be friendly :D● This is the welcome mat to your repo!● A greeting to potential new contributors!● The beginning of a new relationship
![Page 31: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/31.jpg)
@bobcatwilson
How to write a great CONTRIBUTING.md● How to open an issue● How to suggest features● What contributions you’re looking for● Project philosophy● Project roadmaps● Slack/group chat/mailing lists
![Page 32: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/32.jpg)
@bobcatwilson
If all projects were the same….● Who here uses Go?
![Page 33: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/33.jpg)
@bobcatwilson
If all projects were the same….● Who here uses Go?● Who builds and tests ONLY with:
○ go test○ go build
![Page 34: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/34.jpg)
@bobcatwilson
If all projects were the same….● Who here uses Go?● Who builds and tests ONLY with:
○ go test○ go build
● i.e. you never have to use Makefiles, or scripts, etc.
![Page 35: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/35.jpg)
@bobcatwilson
Unless all projects are identical,If you want contributors,
you need to explain how your project works!
![Page 36: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/36.jpg)
@bobcatwilson
Get the process out of your brainand into markdown!
![Page 37: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/37.jpg)
@bobcatwilson
How to write a great DEVELOPMENT.md● The less you assume, the more people can contribute!● Even super experienced folks:
○ Are new to your project○ May use different tools○ Have had different experiences
![Page 38: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/38.jpg)
@bobcatwilson
Even experienced devs use different toolsJaz uses:
● Github● Go● Kubernetes
Andy uses:
● Java● SVN● In-house bare metal
Wendy uses:
● C#● Visual Studio● Azure
![Page 39: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/39.jpg)
@bobcatwilson
How to write a great DEVELOPMENT.md● How to fork● How to setup an environment for development
○ Tool and resource requirements○ Interacting with the system
● How to iterate○ How do you check something works? e.g. tests, poking manually○ e.g. keeping vendor/ up to date, redeploying, cleaning up
![Page 40: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/40.jpg)
@bobcatwilson
Example DEVELOPMENT.md
The knative/serving DEVELOPMENT.md
knative/serving DEVELOPMENT.md
![Page 41: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/41.jpg)
@bobcatwilson
1. Issues2. CONTRIBUTING.md
+ DEVELOPMENT.md
3. A surprise!
![Page 42: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/42.jpg)
@bobcatwilson
Jaz found a bug in your lib!
![Page 43: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/43.jpg)
@bobcatwilson
Jaz found a bug in your lib!
![Page 44: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/44.jpg)
@bobcatwilson
Why 5?
![Page 45: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/45.jpg)
@bobcatwilson
Why 5?
![Page 46: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/46.jpg)
@bobcatwilson
1. Issues2. CONTRIBUTING.md
+ DEVELOPMENT.md
3. Commit messages
![Page 47: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/47.jpg)
@bobcatwilson
Commit Messages
Thanks Steven Erenst for teaching me about the value of commit messages!
![Page 48: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/48.jpg)
@bobcatwilson
![Page 49: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/49.jpg)
@bobcatwilson
Commits often look like this:
“Fix missing logs”
“Fixes #22 and #5”
“Bump the timeout to 20 min”
![Page 50: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/50.jpg)
@bobcatwilson
![Page 51: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/51.jpg)
@bobcatwilson
Example good commit messageSubject Line
Background
Description
![Page 52: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/52.jpg)
@bobcatwilson
y tho
“logrus use full timestamp”
![Page 53: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/53.jpg)
@bobcatwilson
y tho
“Change default action to ‘inplace’”
![Page 54: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/54.jpg)
@bobcatwilson
y tho
“Change git commit to use short ID instead”
![Page 55: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/55.jpg)
@bobcatwilson
Context switching
![Page 56: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/56.jpg)
@bobcatwilson
Context switching
Commit
![Page 57: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/57.jpg)
@bobcatwilson
Context switching
Commit Pull Request
![Page 58: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/58.jpg)
@bobcatwilson
Context switching
Commit Pull Request Issue
![Page 59: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/59.jpg)
@bobcatwilson
Context switching
Commit Pull Request Issue Human
![Page 60: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/60.jpg)
@bobcatwilson
Context switching
Commit Pull Request Issue Human
Bug
Commit Pull Request
CommitCommit
Pull RequestPull Request
Commit
![Page 61: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/61.jpg)
@bobcatwilson
Example good commit messageSubject Line
Background
Description
![Page 62: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/62.jpg)
@bobcatwilson
How to write great commit messages● Subject line (what does this commit do?)● Body that explains what and why vs. how● Two paragraphs
![Page 63: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/63.jpg)
@bobcatwilson
What + Why v.s. HowHow do you fill 2 paragraphs?
● What is the problem being solved?● Why is this the best approach?● What other approaches were considered?● What side effects will this approach have?● What future work remains to be done?
Thanks Thomas Stromberg!
![Page 64: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/64.jpg)
@bobcatwilson
Great docs are a prereqfor a strong contributor base!
![Page 65: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/65.jpg)
@bobcatwilson
Great docs for a better world!● Remote first!● Different lifestyles!● People all over the globe!● Welcome different kinds of contributors!
![Page 66: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/66.jpg)
@bobcatwilson
How?
1. Dogfood your own internal docs
2. Complete PR = Code + Tests + Docs
Make docs part of your process!
![Page 67: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/67.jpg)
@bobcatwilson
![Page 68: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/68.jpg)
@bobcatwilson
Thanks!
![Page 69: Moar quality! Moar inclusivity!€¦ · - Debugging tips. @bobcatwilson. @bobcatwilson. @bobcatwilson. @bobcatwilson ... Get the process out of your brain and into markdown! @bobcatwilson](https://reader033.vdocuments.mx/reader033/viewer/2022051903/5ff475f36522ff1b64651c77/html5/thumbnails/69.jpg)
@bobcatwilson
Links!CONTRIBUTING.md:https://help.github.com/articles/setting-guidelines-for-repository-contributors/
https://opensource.guide/starting-a-project/#writing-your-contributing-guidelines
https://github.com/nayafia/contributing-template/blob/master/CONTRIBUTING-template.md
Community building:https://help.github.com/categories/building-a-strong-community/
https://opensource.guide/starting-a-project/
https://medium.freecodecamp.org/how-to-attract-new-contributors-to-your-open-source-project-46f8b791d787
GitHub and issues:
https://help.github.com/articles/using-templates-to-encourage-high-quality-issues-and-pull-requests-in-your-rep
ository/
https://github.com/codeforamerica/howto/blob/master/Good-GitHub-Issues.md#writing-good-github-issues
https://help.github.com/articles/helping-new-contributors-find-your-project-with-labels/
Commit messages:
Implementing a Strong Code Review Culture
https://chris.beams.io/posts/git-commit/