$30 off During Our Annual Pro Sale. View Details »

Fostering an "Open-Source" Culture at Work

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

Kevin Lamping

October 27, 2015
Tweet

More Decks by Kevin Lamping

Other Decks in Technology

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