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
   

   View Slide

2. #foster
   

   View Slide

3. http://parentprogramming.xyz
   any parents in the crowd?
   
   1-hour interviews with parents in tech
   
   looking to interview folks
   

   View Slide

4. Front-end Engineer at InVision
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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?
   
   

   View Slide

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
   

   View Slide

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.
    

    View Slide

11. #foster
    opencss.klamp.in
    CULTIVATE AN

    OPEN-SOURCE CULTURE
    How-to
    

    View Slide

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?
    

    View Slide

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?
    

    View Slide

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?
    

    View Slide

15. #foster
    opencss.klamp.in
    REDUCE THE FRICTION
    TO CONTRIBUTE
    

    View Slide

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
    

    View Slide

17. I do know it was said by Wilson. w. Wilson on Home Improvement though.
    
    

    View Slide

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.
    

    View Slide

19. #foster
    opencss.klamp.in
    THE #1 FRICTION
    IS FEAR
    Fear of looking foolish
    
    Fear of breaking something
    
    Fear of wasting time
    

    View Slide

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”
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

23. #foster
    opencss.klamp.in
    USE A LINTER
    Reducing fear
    Checks for style and code errors/inconsistencies
    
    ESLint and stylelint
    

    View Slide

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.
    

    View Slide

25. #foster
    opencss.klamp.in
    USE “GIT HOOKS”
    Reducing fear
    pre-commit, pre-push
    
    Run tests/lint before pushing code to other humans
    

    View Slide

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
    

    View Slide

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
    

    View Slide

28. #foster
    opencss.klamp.in
    SHOW EXAMPLES
    Reducing fear
    An example is worth 1000 technical words
    

    View Slide

29. Create a style guide, use a style guide tool
    
    Easier to get started; can copy-paste example as a starting point
    

    View Slide

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
    
    

    View Slide

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.
    
    

    View Slide

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.
    

    View Slide

33. Kent C. Dodds introduced the idea to me via twitter and blog post
    

    View Slide

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.
    

    View Slide

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)
    

    View Slide

36. But he addresses it well. He creates the tests that are failing, outlines the
    requirements, makes a list of to-do items.
    

    View Slide

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
    

    View Slide

38. #foster
    opencss.klamp.in
    EMPATHETIC CODE
    MANAGEMENT
    

    View Slide

39. #foster
    opencss.klamp.in
    A STORY
    Empathetic Code Management
    

    View Slide

40. One app, with many teams
    
    (Pardon the really poor drawings)
    

    View Slide

41. Team Stark
    

    View Slide

42. Team Lannister
    

    View Slide

43. Etc Etc
    
    TROGDOR!!!
    

    View Slide

44. Others that are interesting, but don’t really matter to the main storyline
    

    View Slide

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…
    

    View Slide

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
    

    View Slide

47. Now team in scramble mode
    
    They hadn’t told the lannisters about their work (why would they need to know)?
    

    View Slide

48. Panic sets in
    

    View Slide

49. Lannister already merged and shipped the code.
    

    View Slide

50. Team is relying on those changes for the code that they just shipped. Sooo….
    

    View Slide

51. At this point, people start bracing for a long weekend of refactoring code.
    
    

    View Slide

52. The king is just “work the weekend m’kay” and we’ll do a “tiger team” to discuss this
    on 8am monday morning
    
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

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?
    

    View Slide

56. didn’t Salt n Pepa teach us to push it?
    

    View Slide

57. #foster
    opencss.klamp.in
    DON’T “PUSH” IT
    Separate Infrastructure
    Pushing code out to teams creates unexpected changes if not perfectly
    communicated.
    

    View Slide

58. Pushing it breaks prod. Don’t break prod
    

    View Slide

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.
    

    View Slide

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.
    
    

    View Slide

61. Teams go to the common repo when they’re ready to upgrade.
    
    So app a can be upgraded separate from app b
    

    View Slide

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)
    

    View Slide

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
    

    View Slide

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)
    

    View Slide

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
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

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?
    

    View Slide

70. #foster
    opencss.klamp.in
    SEMANTIC
    VERSIONING
    Passive Communication
    

    View Slide

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.
    

    View Slide

72. #foster
    opencss.klamp.in
    0.10.35
    0.10.36
    Passive Communication
    Small patch change.
    
    Trust, but verify with automated tests.
    

    View Slide

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.
    

    View Slide

74. #foster
    opencss.klamp.in
    0.10.36
    1.0.0
    Passive Communication
    Big change. Expect a good day or two to upgrade.
    

    View Slide

75. #foster
    opencss.klamp.in
    NODE STABILITY
    INDEX
    Passive Communication
    Allows you to introduce new components with a disclaimer. Add index with
    component documentation.
    

    View Slide

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
    

    View Slide

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 :/
    

    View Slide

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.
    

    View Slide

79. #foster
    CONVENTIONAL CHANGELOGS
    ():
    
    
    
    
    autogenerate from git commit messages
    

    View Slide

80. #foster
    CONVENTIONAL CHANGELOGS
    fix(pencil): stop graphite
    breaking when too much
    pressure applied
    Patch Release
    

    View Slide

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)
    

    View Slide

82. #foster
    opencss.klamp.in
    EMBRACE HUMAN
    CULTURE AT WORK
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

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
    

    View Slide

87. View Slide

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/
    
    

    View Slide

89. workingon.co, waffle.io, trello.com
    
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

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.
    

    View Slide

93. Example blog post from the lead maintainer of EmberJS. Will be handy
    reference for future prioritization.
    

    View Slide

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
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

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.
    

    View Slide

98. #foster
    opencss.klamp.in
    BE A GOOD OPEN-
    SOURCE CITIZEN
    How to
    If you’re not an maintainer, you can still contribute well
    

    View Slide

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)
    

    View Slide

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)
     

     View Slide

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
     

     View Slide

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)
     

     View Slide

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
     

     View Slide

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
     

     View Slide

105. #foster
     OPEN-SOURCE CULTURE
     SUMMARY
     ▸Reduce friction to contribute
     ▸Practice empathetic code management
     ▸Embrace the human community
     ▸Be a good open-source citizen
     

     View Slide

106. #foster
     opencss.klamp.in
     RESOURCES
     openresources.klamp.in
     

     View Slide

107. #foster
     RESOURCES
     BOOKS
     ▸ Creativity, Inc
     ▸ Joy at Work
     ▸ Why Motivating People Doesn't Work… and What Does
     

     View Slide

108. #foster
     RESOURCES
     TOOLS
     ▸ eslint.org
     ▸ stylelint.io
     ▸ travis-ci.org
     ▸ semantic-release
     ▸ conventional-changelog
     ▸ waffle.io/Trello
     ▸ Gitter.im
     

     View Slide

109. #foster
     RESOURCES
     PODCASTS
     ▸ Preaccident Investigation
     ▸ The Future of Work
     ▸ Western Devs Episode: Internal Open Source
     

     View Slide

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
     

     View Slide

111. #foster
     opencss.klamp.in
     open.klamp.in
     Read More @klamping
     

     View Slide

112. #foster
     opencss.klamp.in
     openbook.klamp.in
     Stay Tuned @klamping
     

     View Slide