Fostering an "Open-Source" Culture at Work

Even if you're working an entirely closed-source codebase, the chances are high that you're pulling in an open-source project. The popularity of Sass, jQuery, and many others speaks to how well open-source works, when done right.

But the truth is, these projects face the same troubles that many workplaces struggle with. How do they encourage contributions when most contributors only have a few minutes to spare? How do they manage to collaborate on a codebase when everyone lives in a different city and works on different teams? How do they get developers to RTFM?

While not everyone project can be open-source, all of them can benefit from taking an "open-source" approach. In this talk, we'll look at how to foster a codebase and a culture that's open and encouraging to everyone. We'll cover what works and what surprisingly doesn't, all in an effort to foster a more open, maintainable and friendly project.

Slides from CSSDevConf presentation

Transcript

1. #foster opencss.klamp.in FOSTERING AN "OPEN-SOURCE" CULTURE AT WORK Kevin Lamping @klamping opencss.klamp.in
2. #foster
3. http://parentprogramming.xyz any parents in the crowd? 1-hour interviews with parents in tech looking to interview folks
4. Front-end Engineer at InVision
5. #foster opencss.klamp.in OPEN-SOURCE SOFTWARE It’s not about This talk is not about open-source software and why you should use it
6. #foster opencss.klamp.in OPEN-SOURCE CULTURE It’s about It’s about open-source culture, and why it’s important to any company and/or team
7. #foster opencss.klamp.in RELY ON VOLUNTEERS Open-source projects How do open-source projects get people to volunteer their time? OSS doesn’t have a big budget
8. #foster opencss.klamp.in ARE DISTRIBUTED Open-source projects Most open-source projects don't have dedicated, co-located teams. How do they cope?
9. #foster opencss.klamp.in STRUGGLE WITH SCALE Open-source projects How do they support their ever growing user base while staying adaptable? A projects success can also be its demise
10. #foster opencss.klamp.in DO QUITE WELL Open-source projects While there are a million OS projects that fail, many are outstanding successes, because they overcome the problems they face and are stronger for it.
11. #foster opencss.klamp.in CULTIVATE AN
 OPEN-SOURCE CULTURE How-to
12. #foster opencss.klamp.in REDUCE THE FRICTION TO CONTRIBUTE Open-Source Culture How do you get contributions from people who are likely already overworked?
13. #foster opencss.klamp.in PRACTICE EMPATHIC CODE MANAGEMENT Open-Source Culture How can you continue to evolve your product without causing endless headaches for those who have helped you get to where you are?
14. #foster opencss.klamp.in EMBRACE HUMAN CULTURE AT WORK Open-Source Culture Just because it's work, doesn't mean it's not human. How do you build a community that’s supportive and encouraging and avoid the politics?
15. #foster opencss.klamp.in REDUCE THE FRICTION TO CONTRIBUTE
16. #foster BETTER TO HAVE PEOPLE THINK YOU'RE A FOOL THAN TO OPEN YOUR MOUTH AND REMOVE ALL DOUBT. ??? opencss.klamp.in May have been Lincoln that said this, may have been Mark Twain
17. I do know it was said by Wilson. w. Wilson on Home Improvement though.
18. #foster BETTER TO HAVE PEOPLE THINK YOU'RE A FOOL THAN TO OPEN YOUR MOUTH AND REMOVE ALL DOUBT. Wilson W. Wilson opencss.klamp.in Idea is, assume the developers are uncomfortable/intimidated when trying to contribute code.
19. #foster opencss.klamp.in THE #1 FRICTION IS FEAR Fear of looking foolish Fear of breaking something Fear of wasting time
20. #foster “A leader’s job is to drive fear out of the organization so that employees will feel comfortable making decisions on their own. Dennis Bakke ” Assume people are uncomfortable/intimidated. Quotation from the book “Joy at Work”
21. #foster opencss.klamp.in AUTOMATICALLY FIND EASY MISTAKES Reducing fear misspelled variables names, different coding styles, indentation… who uses tabs/spaces, single quotes/double quotes? So much variation in personal style, it’s inevitable there will be differences.
22. It’s nicer to hear from a bot that you’re wrong than a human. As a human, you’re less strict than bots, which hurts in the long run.
23. #foster opencss.klamp.in USE A LINTER Reducing fear Checks for style and code errors/inconsistencies ESLint and stylelint
24. #foster opencss.klamp.in ADD AUTOMATED TESTS Reducing fear Provides newcomers with a set of requirements to test their code changes against Allows much more confidence for newcomers that their changes haven't broken anything Unit, Integration, Visual Makes your job easier, as you can have a better trust that changes won’t break stuff.
25. #foster opencss.klamp.in USE “GIT HOOKS” Reducing fear pre-commit, pre-push Run tests/lint before pushing code to other humans
26. #foster opencss.klamp.in USE CONTINUOUS INTEGRATION TOOLS Reducing fear TravisCI, Jenkins Allow more immediate feedback. Catches weird things. Easier for reviews. Better trust that process was followed
27. #foster opencss.klamp.in LET PEOPLE SCREW UP Reducing fear Spend time trying to prevent it, but also spend time planning for recovery from mistakes. Expect failure. Plan for it. Embracing variability vs. Reducing Variability Reducing is good for things like code style, embracing is good for things like experimental work
28. #foster opencss.klamp.in SHOW EXAMPLES Reducing fear An example is worth 1000 technical words
29. Create a style guide, use a style guide tool Easier to get started; can copy-paste example as a starting point
30. #foster opencss.klamp.in DOCUMENTATION WON’T BE READ Reducing fear It’s tough to read all the documentation out there and not everyone has time. Also, many times people don't learn best via written documentation. If people aren't reading the docs, maybe that's a sign that you should try a different form of documentation/training
31. #foster opencss.klamp.in STILL, WRITE GOOD DOCUMENTATION Reducing fear Docs should be more useful to the main dev team, as a quick way of pointing people in the right direction.
32. #foster opencss.klamp.in MAKE IT EASY FOR FIRST-TIMERS Reducing fear Have a list of bugs reserved for first-timers; simple, changes with well-defined requirements.
33. Kent C. Dodds introduced the idea to me via twitter and blog post
34. #foster THE HARD PART OF GETTING INTO OPEN SOURCE ISN’T THE IMPLEMENTATION, BUT FIGURING OUT HOW TO ACTUALLY CONTRIBUTE Kent C. Dodds TEXT The hard part of getting into open source for the first time isn’t the implementation of a feature, but figuring out how to actually contribute code.
35. At first this threw me off. “Only accept from first-timers?” Isn’t that a little biased (says the experienced programmer who has had the luxury of learning on the job)
36. But he addresses it well. He creates the tests that are failing, outlines the requirements, makes a list of to-do items.
37. #foster opencss.klamp.in EMBRACE NON- CONTRIBUTORS Reducing fear Time is limited, making a contribution to a big framework takes a lot of time that people with project deadlines don't have Don't fret too much about it. Be opening and encouraging, but not pushy Don't try gimmicks to get contributions. Contests only serve to undermine efforts
38. #foster opencss.klamp.in EMPATHETIC CODE MANAGEMENT
39. #foster opencss.klamp.in A STORY Empathetic Code Management
40. One app, with many teams (Pardon the really poor drawings)
41. Team Stark
42. Team Lannister
43. Etc Etc TROGDOR!!!
44. Others that are interesting, but don’t really matter to the main storyline
45. Starks have been working 3 weeks on this new feature. A feature that requires some common code to behave a specific way. They’re a day away from releasing…
46. Unfortunately, yesterday, lannisters released update w/modification to code that Team stark was expecting to work a specific way. Except it no longer does
47. Now team in scramble mode They hadn’t told the lannisters about their work (why would they need to know)?
48. Panic sets in
49. Lannister already merged and shipped the code.
50. Team is relying on those changes for the code that they just shipped. Sooo….
51. At this point, people start bracing for a long weekend of refactoring code.
52. The king is just “work the weekend m’kay” and we’ll do a “tiger team” to discuss this on 8am monday morning
53. #foster opencss.klamp.in SEPARATE YOUR INFRASTRUCTURE Empathetic Code Management This could be avoided. Issue was two-fold No one responsible for infrastructure code and communication. Infrastructure code being “pushed” out to teams “Infrastructure” could be a style guide/core JS/CSS.
54. #foster opencss.klamp.in INFRASTRUCTURE TEAM & CODEBASE Empathetic Code Management Need separate infrastructure team, even if one person, to manage changes. Need a separate codebase to manage upgrades
55. Most of the time, the common codebase gets pushed out to all the apps on update. You want to get features out there, right? So what do you do?
56. didn’t Salt n Pepa teach us to push it?
57. #foster opencss.klamp.in DON’T “PUSH” IT Separate Infrastructure Pushing code out to teams creates unexpected changes if not perfectly communicated.
58. Pushing it breaks prod. Don’t break prod
59. it’s a bad idea, open source world has figured that out. You will break prod with this model. Again and again and again. You’re pushing code out to an untested environment.
60. #foster opencss.klamp.in “PULL” IT INSTEAD Separate Infrastructure Allow the apps the room to "pull" in the code when their ready. This isn't an uncommon model. Almost all open-source projects out there follow it.
61. Teams go to the common repo when they’re ready to upgrade. So app a can be upgraded separate from app b
62. Then when app b has finished their dev cycle, they can upgrade on their own time. Package managers like NPM follow this model (unless you're using the latest flag, which again, you probably shouldn't be)
63. #foster opencss.klamp.in LOWERS RISK IN UPDATES Benefits Teams able to fully regression test code, at their own pace (no weekends) Test changes with small pilot groups If something breaks due to the release, each team has option to delay upgrade until later Ability to rollback an update because infrastructure is versioned
64. #foster opencss.klamp.in FASTER ITERATION Benefits Able to release code quicker. Shortened release cycles, each version change will be more bite-sized, allowing teams an easier upgrade. Doesn't mean code isn't tested. infrastructure team should have regression tests they run. Also doesn't mean app teams on their own, or that the infrastructure team is free to make any change they want. Teams should be there for each other (empathy)
65. #foster opencss.klamp.in TAKES MORE EFFORT Drawbacks takes effort for a team to pull down code, compared to it automatically being pushed to them trade-off of the model and needs to be understood and accepted as part of the deal. Easy to blame pull model; important to look deeper at the problem before abandonment
66. #foster opencss.klamp.in VISUAL INCONSISTENCIES Drawbacks hardest pill to swallow, effects app end-user If your infrastructure code includes visual design, splintering versions means having an inconsistent experience across apps which are supposed to look similar.
67. #foster opencss.klamp.in PLAN FOR IT If you know you have a series of visual updates that need consistency across the site, go through the effort to plan a combined release of these changes. Along with this, get in touch with the app teams and see if you can do a coordinated release for all of the apps. It does mean letting go of the benefits described above, but hopefully this isn't a common occurrence.
68. #foster opencss.klamp.in PASSIVELY COMMUNICATE Empathetic Code Management Give information passively, to avoid spamming inboxes and and save time spent in endless meetings
69. https://twitter.com/sosowski/status/517005067334205441 Many ways to do versioning, including the microsoft way. Other’s include dates. But what if we can send information for free with every update?
70. #foster opencss.klamp.in SEMANTIC VERSIONING Passive Communication
71. #foster opencss.klamp.in Major.Minor.Patch Passive Communication MAJOR version when you make incompatible API changes, MINOR version when you add functionality in a backwards-compatible manner, and PATCH version when you make backwards-compatible bug fixes.
72. #foster opencss.klamp.in 0.10.35 0.10.36 Passive Communication Small patch change. Trust, but verify with automated tests.
73. #foster opencss.klamp.in 0.10.36 0.12.0 Passive Communication Larger change. Expect a little bit of work regression testing and updating code usage.
74. #foster opencss.klamp.in 0.10.36 1.0.0 Passive Communication Big change. Expect a good day or two to upgrade.
75. #foster opencss.klamp.in NODE STABILITY INDEX Passive Communication Allows you to introduce new components with a disclaimer. Add index with component documentation.
76. #foster NODE STABILITY INDEX 0 - Deprecated 1 - Experimental 2 - Unstable 3 - Stable 4 - API Frozen 5 - Locked Can have an experimental component live next to a stable one Allows more flexibility
77. #foster opencss.klamp.in UPDATE OFTEN Passive Communication Update regularly, otherwise it’s meaningless and not worth it. Mgmt might also not like it b/c it reveals a certain amount of hesitation around code :/
78. Another form of passive communication is changelogs Change log is a file which contains a curated, chronologically ordered list of notable changes for each version of an open source project. Make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.
79. #foster CONVENTIONAL CHANGELOGS <type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer> autogenerate from git commit messages
80. #foster CONVENTIONAL CHANGELOGS fix(pencil): stop graphite breaking when too much pressure applied Patch Release
81. #foster CONVENTIONAL CHANGELOGS perf(pencil): remove graphiteWidth option BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reason. Major Release (big breaking change)
82. #foster opencss.klamp.in EMBRACE HUMAN CULTURE AT WORK
83. #foster opencss.klamp.in DON’T BECOME GOOD AT MEETINGS Embracing Human Culture These behaviors build silos by keeping communication hidden. Anyone not at a meeting won’t know the information.
84. #foster opencss.klamp.in CLOSED-SOURCE CREATES SILOS Embracing Human Culture Unless publicly recorded, meetings and emails are “closed-source”. Meetings & emails don’t scale. This creates silos of information.
85. #foster opencss.klamp.in SILOS FOSTER POLITICS Embracing Human Culture Silos encourage politics & discourage outside voices. Becomes more about who you know than what you can find out. How is someone supposed to help when they don’t know the details? Communicate in the open, via github, chat rooms, message boards, publicly recorded hangouts
86. #foster opencss.klamp.in HAVE A PUBLIC CHAT ROOM Embracing Human Culture Slack/Hipchat/gitter.im Chat history that’s searchable Easier for quick discussion. Team can help out, instead of an individual. People can lurk. Allows for distributed/remote work
88. #foster opencss.klamp.in PRIORITIZE IN THE OPEN Embracing Human Culture Work as if you’ll never meet your users face-to-face in real life. Follow a “remote-first” model. https://www.getdonedone.com/remote-first-approach-workplace/
89. workingon.co, waffle.io, trello.com
90. #foster opencss.klamp.in COMMUNICATE PRIORITIZATION Embracing Human Culture Some people assume that because you're in the same company, you have the same priorities as them (and will therefore do their work for them). You (and your management) need to have a strategy for this. If not, all new work will halt while you hand-hold teams.
91. #foster opencss.klamp.in GROW THE BACKLOG Embracing Human Culture Don't fear an endless backlog. It's okay to have too much work to do. It’s better to track the work than forget it.
92. #foster opencss.klamp.in LEAVE TIME TO WRITE Embracing Human Culture Blog posts. Weekly ‘write ups’. A-ha’s. Keep a history of why decisions were made, you'll forget why a month later otherwise when someone asks.
93. Example blog post from the lead maintainer of EmberJS. Will be handy reference for future prioritization.
94. #foster opencss.klamp.in CODE REVIEW TIMELINES Embracing Human Culture If you know you don't have time to review a PR right away, make a quick comment saying so. Everyone understands people get busy Bigger PRs require more time, and likely more cycles of feedback. Make sure both sides understand this. Same for emails/other communication
95. #foster opencss.klamp.in CONSTANTLY SEEK FEEDBACK Embracing Human Culture People have a tendency to hold back “small things” until the become big. Talk about importance of “small things”. It takes time to build rapport with contributors.
96. #foster opencss.klamp.in BE THANKFUL FOR CRITICISM Embracing Human Culture Story: I asked for feedback on a change, didn't receive any, until someone commented the change will "suck the soul out of the codebase" I could be upset about the rudeness, or I could be empathetic towards the person. Most (myself included) want to hide feelings; hold them in until they can't It may feel good/righteous to call someone out, but it doesn't promote a healthy project ecosystem
97. #foster WE’VE PAID PEOPLE FOR THEIR HANDS FOR YEARS, AND THEY WOULD HAVE GIVEN US THEIR HEADS AND HEARTS FOR FREE IF WE’D ONLY ASKED. Bob Chapman, Truly Human Leadership opencss.klamp.in Contributors are volunteers when it comes to their ideas. You can't force good behavior. You have to foster it.
98. #foster opencss.klamp.in BE A GOOD OPEN- SOURCE CITIZEN How to If you’re not an maintainer, you can still contribute well
99. #foster opencss.klamp.in READ THE DOCS Be a good open-source citizen read the contributing guide, changelogs, etc If they suck, contribute your own (or at least mention it as an issue)
100. #foster opencss.klamp.in ASK IN THE OPEN Be a good open-source citizen ask questions in the open (chat rooms, forums) if you’re comfortable lurkers, latecomers benefit Automatically turned in to “docs” (if chat history searchable)
101. #foster opencss.klamp.in TEST CHANGES Be a good open-source citizen Hardest part of updating is testing Test on your machine, for changes you (or others) have made Needs lots of Quality Assurance
102. #foster opencss.klamp.in PROVIDE FEEDBACK Be a good open-source citizen Make sure there is a good rapport Be objective with feedback Talk with feelings: “this change gives me a weird feeling” (non-judgemental, doesn’t say that it’s wrong, just that it feels wrong)
103. #foster opencss.klamp.in CONTRIBUTE YOUR BEST Be a good open-source citizen Don’t worry about contributing what’s “most needed” We need passionate people Find what motivates you and chase it Don’t prioritize for the project owner, prioritize for yourself
104. #foster opencss.klamp.in BE PATIENT & GIVE HUGS Be a good open-source citizen Don’t have to be physical hugs; it never hurts to say thanks and show appreciation, or be an empathetic ear to a maintainer who needs to vent
105. #foster OPEN-SOURCE CULTURE SUMMARY ▸Reduce friction to contribute ▸Practice empathetic code management ▸Embrace the human community ▸Be a good open-source citizen
106. #foster opencss.klamp.in RESOURCES openresources.klamp.in
107. #foster RESOURCES BOOKS ▸ Creativity, Inc ▸ Joy at Work ▸ Why Motivating People Doesn't Work… and What Does
108. #foster RESOURCES TOOLS ▸ eslint.org ▸ stylelint.io ▸ travis-ci.org ▸ semantic-release ▸ conventional-changelog ▸ waffle.io/Trello ▸ Gitter.im
109. #foster RESOURCES PODCASTS ▸ Preaccident Investigation ▸ The Future of Work ▸ Western Devs Episode: Internal Open Source
110. #foster RESOURCES LINKS ▸ The Pull Request Hack ▸ Turds aren’t always turds ▸ Using Open Source Methods in a Private Company ▸ Internal Open Source: Changing Internal Culture For The Better (Presentation) ▸ Bring Kindness back to Open Source ▸ First-Timers Only ▸ And more at http://openresources.klamp.in
111. #foster opencss.klamp.in open.klamp.in Read More @klamping
112. #foster opencss.klamp.in openbook.klamp.in Stay Tuned @klamping