Series:software outreach Blog


LibrePlanet talk: Sharing strategies for welcoming newcomers into FLOSS projects: First-timers-only, list moderation, and more

by warren with liz | about 6 years ago | 2 | 5

Hi all, I'm preparing for a talk with Liz Barry ( @liz) at LibrePlanet 2018 on Sunday at

It'll livestream at https://libreplanet.org/2018/live/

The program is here: https://libreplanet.org/2018/program/

Sharing strategies for welcoming newcomers into FLOSS projects: First-timers-only, list moderation, and more

Room: 32-123 - Time: 15:25-16:10 (Eastern Time)

Since early 2016, Public Lab has worked to make our free software projects more welcoming and inclusive, and to grow our software contributor community in diversity and size. We have learned from and incorporated strategies from other communities like the Hoodie Project, SpinachCon, and FirstTimersOnly.com, and shared our own ideas, and this session will cover a range of principles and strategies that have emerged across a number of separate efforts in different FLOSS projects. Topics will include:

1) friendliness,

2) Codes of Conduct,

3) first-timers-only issues,

4) welcoming pages,

5) social media outreach,

6) code modularity,

7) ladders of participation,

8) continuous integration,

9) friendly bots, and

10) evaluation.

Slides

Read more Follow

community presentations event presentation

Software outreach: Modularity is great for collaboration

by warren | about 6 years ago | 0 | 8

Just as Summer of Code deadlines are looming, I wanted to write a bit about modularity, as I think it'll be useful for our mentors and students this coming SoC season.

I'm mostly talking about open source software collaboration here, but I really believe that this approach can work for collaboration of all kinds -- from writing projects to hardware prototyping. We're getting better at modularizing things like the new microscope projects, the spectrometer, and of course various datalogging projects.

Small modular changes are great for newcomers -- and for everybody else!

Modularity may sound kind of boring as a topic -- and it's relationship to outreach and onboarding not immediately apparent. The basic idea is to isolate functionality in smaller chunks of code which are easier to reuse, understand, and maintain.

But this is exactly what newcomers need -- to not have to know a much larger whole system to be able to get your bearings, and to know what a chunk of code will receive as input, and should generate as output. It also makes for very test-able code, and code which has a minimal "entanglement" with other parts of a complex system.

I encourage ANYONE doing open source work to think hard about how their project can be better modularized -- along with the various other strategies we've been covering in this series, it can lead to a major influx of new contributors!

(There's been a lot written about the modular design pattern of much modern JavaScript, too!)

For these reasons, we now require all contributions to work in small pieces which we can scan through quickly, write simple tests for, and publish to our live site within a day or two. This applies to Summer of Code projects as well as any given feature or bug fix on the site.

One big benefit is that you'll see your work published on the live site very quickly! Sometimes even the same day it's written. We ask Summer of Code students to present a new PR at least once per week; many submit several.

image description

Breaking it up

When a bug or a feature request is first proposed (even after there's been a consensus on exactly what it should do, which can take a while!) it's rarely something small and self-contained enough to be a good "chunk" for solving -- for either newcomers or long-time contributors. So we ask everyone to try to break bigger projects down into smaller, separately solve-able parts.

It often takes a lot of work to do this -- and it's a bit of a skill! Sometimes it can take some deeper familiarity with the code organization, but not always. Here are some tips:

  • separate how a feature will look from what it will do
  • develop back-end functions and test them before developing user interface - so the code can be published and tested BEFORE we invite users to try them out!
  • think of reducing the amount of context a function needs. Writing a test is a great way to do this -- what's the minimum amount of test data a function needs to demonstrate that it works?
  • make a checklist of different parts -- say, how it'll look to the author, vs. how it'll look to someone else, vs. to a moderator, for example
  • make sure you have all the needed info -- exact text that'll appear, exact URLs where it'll show up
  • generally, each part should be less than 100 lines of code -- and many are far less; just a couple lines, or 10-line features are common. This makes pull requests easier to read through, among other benefits.

For an example, check out this beautifully broken-up giant project: https://github.com/publiclab/plots2/issues/1416

What's worked for you, in terms of breaking things up?

Versioning and cross-repository work

Sometimes, for a big enough feature, we've found that it's worth actually spinning out a separate project; we've done this for:

And many more! https://github.com/publiclab

We've done this when, for example, the sub-project is largely in a different language (like JavaScript), or when we think other projects might be interested in using it. The benefit is that people working on a highly specialized function can do so in a more controlled, self-contained -- and simpler! -- environment. And that it's possible to recruit help from other projects who may want to use that function along with you (read below for more on this).

However, this can tend to split your community -- the issues listings aren't shared, and it can be hard to maintain a sense of continuity across projects. We've solved this a bit with our cross-project Community Toolbox welcoming page:

https://publiclab.github.io/community-toolbox/#r=all

This lists first-timers-only and other issues for all Public Lab projects on GitHub. But we can surely do even better, and experimenting with GitHub "teams" as well.

A bit of history

Although modularity is something fundamental in basically all coding, our first major foray into broader structural came with GSOC 2014 student Justin Manley's (@justinmanley) work on MapKnitter. He pushed us not only to develop clearer welcoming documentation for newcomers, but also to spin out projects like the heart of MapKnitter, Leaflet DistortableImage. We also took major inspiration from the work of the Hoodie project, which champions the "first-timers-only" workflow we use today.

Small modules as a design pattern has been championed by the Node.js community, where the NPM repository of modules has led to people developing tiny programs which, for example, provide formatting for numerals, or can just capitalize words. These tiny modules are interconnected into collections of thousands to form bigger programs, and to do this without constantly breaking, they follow something called Semantic Versioning. This means that the version number of each "release" of a mini-program carries information about what's changed.

These modules do their utmost to "not break" projects they've been used in, and so a version change from v1.0.0 to v2.0.0 indicates that some behaviors have been changed -- any lesser change, for example just adding new functionality without breaking old functionality -- would be indicated by a minor version bump, like v1.1.0 to v1.2.0. Bug fixes are the last digit. This may seem extraordinarily persnickity, but it provides confidence that a program will be pretty stable -- it's a kind of "agreement" between upstream and downstream programmers in interrelated projects.

We strive for something similar with tests. By accompanying your code with tests, and limiting the size of your changes, you can give other coders the confidence that your code won't break, or if it does, it'll complain by failing some tests! When done right, this can actually give newcomers a lot more confidence that they can make major changes and know (if tests are well-written) that they haven't broken anything.

image description

Above, a checklist by @mridulnagpal for our Geographic features

Putting it in practice

OK, so what does this mean for you?

If you're part of the PL code reviewers group, and you're there to help people out, try looking at GitHub issues that are too big to be solved in one big chunk, especially for newcomers. We use the tag break-me-up for these.

In the comments of an issue that could use breaking up, try to develop a checklist of things you can see happening one by one. Checklists can also help you recruit people to take on one or more steps, sharing the work. Do any of the make great first-timers-only issues?

As you complete each item, check it off the list and link to the issue or pull request where it was solved -- and thank the person who solved it!

Finally, if you propose a feature or bug fix, work with others to plan out these steps -- and ask for help! We're eager to pitch in.

Read more Follow

website software gsoc web

Software outreach: Codes of conduct and friendliness

by warren | over 6 years ago | 0 | 3

This is part 2 in our Software Outreach series -- and I wanted to note that a lot of things we're doing in software contributor outreach at Public Lab also apply to outreach more broadly across Public Lab.

Totally not obvious

These topics may seem obvious to some people. But if you poke around the open source world (and the world at large, sadly), they really really aren't. I've seen some terrible things said on public mailing lists, and I'm proud of being part of a community that doesn't allow that kind of behavior. I'm especially proud to be part of a community that is actively nice to one another. Whenever I'm feeling impatient, annoyed, or just didn't eat my oatmeal that morning, I try to remember this and to put my best foot forward.

Codes of Conduct

Codes of Conduct are a good example of something that's not just for our software community -- ours applies across all virtual and in-person spaces where Public Lab is hosting. The past few years have seen a dramatic rise in the use and application of codes of conduct, and Public Lab's was adopted midway through 2016, and has been used as a model for the CoC of other groups since then:

We are coming together with an intent to care for ourselves and one another. We want to nurture a compassionate democratic culture where responsibility is shared. We -- visitors, community members, community moderators, staff, organizers, sponsors, and all others -- hold ourselves accountable to the same values regardless of position or experience. For this to work for everybody, individual decisions will not be allowed to run counter to the welfare of other people. This community aspires to be a respectful place both during online and in-person interactions so that all people are able to fully participate with their dignity intact. This document is a piece of the culture we're creating.

Codes of Conduct directly address the fact that without being assured of being treated respectfully, we cannot expect people to join in, let alone collaborate. They are also an acknowledgement that incidents of poor conduct disproportionally affect those who are already structurally excluded or marginalized, and that affirming -- and working to achieve -- a harassment-free environment is a prerequisite to an inclusive space.

I was impressed in 2015 by the Hoodie project's placement of their Code of Conduct up front and center on Slide 2 of their presentation at a BostonJS meeting. Codes of conduct are now standard in many (but not all!) open source communities, with GitHub even prompting all projects to include one in their project code.

Trumpet your Code of Conduct! It speaks volumes to people.

At the recent Google Summer of Code Mentor Summit, there was a lot of discussion (led by the amazing folks at Systers) of conduct, but also of questions of tone -- and one person mentioned that they have heard people try to excuse unpleasant tone (or worse!) if the guilty party is "technically excellent" -- how utterly awful! If someone is not able to conduct themselves with basic respect, they are simply not welcome in our community, and to be honest, we shouldn't be surprised if they aren't good at collaborating with others.

There's a LOT more that could be written about CoCs -- how they work, what to put in them, how to respond to violations, privacy, and so on. Here I just want to say that they're incredibly important, and you should read more about them:

image description

Friendliness

Ensuring that people will be treated respectfully shouldn't have been such a high bar, and we're seeing more and more communities recognize that this should be a basic right and expectation for anyone. But we can do more! It's extra important to be welcoming and friendly -- it's hard to imagine how you could overdo this. Hoodie writes a lot about their "rolling out the red carpet for newcomers", and they're a real model for us.

At the GSoC summit, in one session, during a discussion about friendly tone, one person noted that they were often a bit afraid to email the community list for their project because some people could be abrasive -- and they were actually one of the maintainer/leaders of the project! That isn't right -- and just think what a newcomer to the project must feel if that's the tone of community discussions.

We take every opportunity to thank people -- you can't be too nice! -- and one thing that really helps is: emoji. No kidding -- use them! Learn them! Hoodie does this really well (and so does their "first timer bot". I particularly like the "red balloon" one for expressing appreciation.

Get out there and make sure people know they're welcome! They're not clairvoyant -- you need to put some work into it!

image description

Next up

I was going to write more about First Timers Only -- but there's so much to say about it that I'm going to save it for its own post.

Stay tuned, and remember: broadening participation in your project -- especially from groups who are often excluded -- will make your project stronger -- as well as for inclusivity for its own sake!

Read more Follow

community outreach organizing wwg

Software outreach: a blog series

by warren | over 6 years ago | 0 | 5

Since early 2016, Public Lab has worked to make our open source software projects more welcoming and inclusive; to grow our software contributor community in diversity and size. This series collects some of those strategies and initiatives.

I've written a bit before about software outreach at Public Lab, but I'm interested in taking a broad overall look at the specific strategies we've developed, borrowed, and built on since around April 2016, when we started this initiative. This will be a series, and I'll be collecting resources on this page. (Above: GitHub profile icons of some of our contributors)

What's this series for? A set of experimental new strategies and patterns for outreach have emerged over the past 2-3 years which are rapidly changing the landscape for newcomer engagement. I'm excited because they hold promise for more welcoming (and technically superior!) project growth which also support more diverse and equitable communities.

Starting point

We started out pretty "stuck," like many open source projects. From 2010-2016, we had only 16 contributors, total, 6 of whom were part of our Google Summer of Code programs (today we have over 100; we're still a small project, but growing fast). Our code was byzantine -- not because we were terrible coders, but because we were all busy, and we put new feature development before all else. Documentation, code cleanliness, install process, and even updating to the latest versions of our dependencies, all fell by the wayside as we made pragmatic decisions -- after all, I was the only consistent long-term developer, and I had something like 1/3 or 1/4 time devoted to this.

Our first foray into better onboarding was led by @justinmanley, one of our earliest and best GSoC contributors, who wrote this excellent post on how to reform and improve our code and outreach strategy. He did a huge amount to rework our code and systems to set us on the right track. With his help, we were ready for the next step...

SpinachCon

Three events led to our completely changing our direction. First, SpinachCon (in 2016), hosted by Shauna Gordon-McKeon and Deb Nicholson, was a great -- and humbling -- opportunity to try to get our code to be installable by newcomers. We'd estimated 30-60 minutes, after much work (even worse, in the past our GSoC students had sometimes taken more than a day to get dependencies installed!). We found several people who couldn't install our code at all over a couple hours. We spent a lot of time after that to get the install process down below 15 minutes, with an install video and a standard install environment in a free VM service, Cloud9, and things have improved a huge amount since then. Without this initial step, none of the following strategies would have worked!

First-timers-only

Second, in the spring of 2016 I attended a fantastic set of talks at BostonJS, which highlighted both the need for a wider conception of who contributes (including issue creators, commenters, etc) and, from Gregor Martynus of the Hoodie project, a whole new framework for thinking about building a contributor community. Click the link above to read more, and I'll be writing more about this soon, but I learned about the First-Timers-Only "movement", and really loved Gregor's attitude of "rolling out the red carpet for new contributors."

image description

Diversity and project growth

It really seemed to me that Hoodie might even be more interested in recruiting and welcoming newcomers than in actually writing code! I was game -- writing a first-timers-only issue usually takes longer than solving the issue yourself. It's aimed at inviting someone new into the project, using a small but substantive issue to be solved as your initial point of collaboration, and as the start of a conversation and a relationship.

But I was wrong about one thing; as I learned in the coming months as we adopted this approach, a focus on first-timers really is an investment in the long-term growth of a community, both in size and diversity. It's a commitment to supporting people to take their first steps, but it recognizes that it takes work to do so, and that this work is totally worth it.

And in my mind, it emphasizes equity and diversity as core values, not only because they match our personal values, but because we recognize that they are fundamental to improving our work and ourselves. At the recent Google Summer of Code Mentor Summit, one thing I really appreciated hearing from a few people was that diversity was important to the success and growth of their project -- to incorporate new ideas and perspectives, and to be shaped -- transformed -- by them. It's a relief to hear people acknowledge that they're not just looking for someone to type out some code, but some insight, some human qualities, that they can't achieve without diversity.

Transformation

So, before we start diving into the actual strategies in subsequent posts, I'll say that one thing I've learned is that doing good software outreach means acknowledging that your own work must change. Not only in shifting from direct coding work to organizing and cultural work, but also in transforming your own coding style and even your project architecture (see Modularity, in an upcoming post) to make it easier for others to enter into your work and work with you. Good outreach will make you a better coder!

So thanks to everyone who's helped make this journey possible! I'm sure I'll be naming a lot of amazing people and projects as this series develops.

Up next: Friendliness, codes of conduct, and first-timers-only. Read more of this series on this page.

Also: do you have ideas or suggestions? We're seeking submissions for this series -- leave a comment or reach out to jeff@publiclab.org!

Read more Follow

web-development software outreach development

Help Public Lab’s software grow by joining a supportive team

by warren | over 7 years ago | 14 | 2

PublicLab.org and PL's other open source software is written, maintained, and dreamed up by community contributors, just like the techniques you see on PublicLab.org itself. While you can read about our software development projects at https://publiclab.org/wiki/developers, we know not everyone can jump into being a code contributor -- but we also know there are lots of other ways you can help out, even without taking on a coding task.

And with our recent work in recruiting first-timer code contributors generating exciting growth in our software contributor group, we're looking to define clear ways others can get involved in more of a supportive role.

Types of support

I've looked at some of the ways people have played a valuable supportive (or mentoring) role -- like in our #gsoc program each summer -- and found that some don't take a huge amount of time or commitment, but can really make a difference. Here are a range of different types of involvement -- and keep in mind that many people do a combination of these:

  • Problem solvers: swoop in when someone is really stuck and help crack the nut!
  • Reviewers: check in on a pre-defined schedule to look over submitted code and comment on style, structure, etc
  • Connectors: greet, provide support, regular friendly check-ins, links to resources, and encouragement to newcomers
  • Community reps: be the voice of the broader Public Lab community in shaping new features

(forgive my slightly corny naming system!)

Different capacities

The key here is that:

  • there are ways to help that can fit your schedule
  • we need help with non-coding support as well

For example -- a Reviewer might do a lot of good just by checking in once a week to look over current pull requests, to see if they're missing anything, or make any obvious mistakes. This could be just a calendar reminder at the 15-20m you know you'll have free each Friday, say.

A Connector might check in once daily but only for 10 minutes, just to thank new people for their involvement, or to encourage them to open a pull request with their latest code if they get stuck (so others can check on their work and offer help).

A Community rep can offer their knowledge of how the PL community works (or doesn't!) without having to know anything about coding. They context to a bug or purpose for a feature request.

And so on. What's helpful for me, to match you with a role, is to know:

  • how much time you've got (even 5-10m per week can be helpful!)
  • what your interests or background are
  • what your GitHub username is!

And keep in mind, this is a bit of an experiment! We'd love to better connect the PL community with our quickly-growing software contributor community, and this is just one way we're hoping to help.

Read on to learn more about each role, and volunteer in the comments if you'd like to get plugged in!

Choose a role

We'll be creating a "team" for each of these on GitHub (https://github.com/orgs/publiclab/teams); on there, you can notify each by typing @publiclab/teamname in a comment. So please share your GitHub username with us in the comments to sign up!

(Illustrations/mascots sought for each these, haha)

Problem solvers

@publiclab/solvers - Everyone gets stuck sometimes, and some people are just good at teasing out what went wrong. If you're particularly familiar with Ruby on Rails, or with a specific portion of our codebase, this could be you! No obligation to actually fix problems, but just to take a look and suggest a way forward, or a way to test assumptions and debug. We especially think writing tests is a great way to debug!

Availability: we'll ping you with a @publiclab/solvers mention, or you can just look at recent pull requests; maybe once every week or two. Unsubscribe from project-wide notifications!

Variation: Pre-schedule time each week or month to check in on recent pull requests and review code for problems and style/structure. We've told contributors that reviews happen on Tuesdays and Fridays, so these are good times to check i, and look specifically at the "Files changed" tab of each PR to read through submitted code. You can:

  • request changes for code cleanliness or commenting
  • ask people to specify what issue their PR fixes, especially using the text "fixes #1234" so that the PR actually auto-closes the issue once accepted
  • ask for clarifications or suggest tests

For pre-scheduled solving, consider setting your project notifications (see below) to Ignore so that you don't get any emails, and just check in on your own schedule!

Connectors

@publiclab/connectors - Often, it makes a big difference to newcomers to simply hear some encouragement and thanks, both in response to comments like "Can I try to fix this one?" and after a fix is completed, say, in a tweeted thank-you. To do this, look for newcomers in recently updated issues or subscribe to notifications for the whole project and look out for people asking to get involved. Even if you're just saying hello to people, and offering encouragement, that's a lot of help -- you don't need to code to do this!

If you can help people find documentation, tutorials, or Stack Overflow pages to guide them, that's really helpful too! We've also heard from some contributors that it's really helpful to have a real live person (via chat, for example) there to say hello, even if all they do is be friendly and point people at the right resources.

Availability: this is the most day-to-day kind of work -- it's helpful to reply quickly to newcomers with a welcoming hello -- though the message can be "saved reply" to make this quick (see below). And beware -- the project-wide notifications can be high-volume. You shouldn't have to actually spend lots of time with anyone in particular, but it'd be great if folks already on IRC could just keep an eye out for newcomers asking questions.

Community reps

@publiclab/community-reps - It's difficult for newcomers to really understand the complexities and context for different site features, so we'd love to have some people just explain why features or systems are important, and how they're used. You don't need to know anything about software for this one -- it's just helpful to link to where on the site a feature would show up, and help new coders understand what their contribution will mean.

Availability: Once a week or so, we'll mention @publiclab/community-reps to notify you of where you could be of assistance. Unsubscribe from project-wide notifications!

Resources

There are some important tools available to help you be a good code mentor or helper:

  • Ask for help! Mention another team from above to trigger a notification (@publiclab/reviewers,@publiclab/solvers,@publiclab/@designers`) or just ask me (@jywarren on GitHub)
  • Saved replies are a GREAT GitHub feature to streamline your most common responses with standard text; copy mine here: https://gist.github.com/jywarren/c9a80e0e53f42208974683aa01c623c8
  • Calendar reminders (check in once weekly? Once monthly?)
  • Email notifications -- mostly, I'd say turn these off as soon as you're added to a team! If you get too many, you'll start ignoring them. Tweak them here: https://github.com/settings/notifications and on the project GitHub page: https://github.com/publiclab/plots2, but for most teams listed above, you can just set it to "Not watching" and listen only for when you're specifically mentioned by @name, when you'll get an email notice.

Sign up now!

So, again, just leave a comment below with your GitHub name to join a team, and feel free to ask questions or make suggestions!

And finally, if you find it's too much, please don't hesitate to take a break or withdraw! We definitely don't want to overload people and we very much understand that everyone's got a lot going on in their lives!

Read more Follow

software gsoc web coding

Create a welcoming "first-timers-only" issue to invite new software contributors

by warren | over 7 years ago | 2 | 9

We've been doing some serious outreach for our software contributor community -- that is, people who help us make PublicLab.org and other Public Lab software, through coding, designing, testing, and other helpful tasks.

One way we've been doing this is through first-timers-only issues, which are written in a very engaging, welcoming way, far differently than the usual "just report the bug" type of GitHub issue. To read more about these, check out firsttimersonly.com (the lead image is from their site), which really captures how and why this works, and is beginning to be a movement in open source coding outreach! Beyond the extra welcome, this also includes getting such well-formatted issues out in front of lots of people who may be contributing to open source software for the very first time.

It takes a LOT of work to make a good issue of this type, and we often walk through each step required to actually make the requested changes -- the point is to help newcomers understand that a) they're welcome, and b) what the collaboration workflow looks like.

Our current list of unsolved first-timers-only issues can be found here:

https://code.publiclab.org#r=all

And we try to keep at least 3-4 of them in there at all times!

What makes a good first-timers-only issue?

Good issues for newcomers are usually just a few lines of code, and provide:

  • context for the change -- how it fits into the big picture
  • a clear description of what's wrong and/or what needs to be different
  • a link to the page on the live site where you can see where the change will go
  • a link to the lines of code that need to change
  • step-by-step instructions on making the change and submitting it
  • who to ask for help
  • friendliness!

You can see an example of one here: https://github.com/publiclab/plots2/issues/3688

It should take longer to write such an issue than it would take you to do the fix yourself if you're a coder. And you can start with an existing issue, such as a help-wanted issue, which have some of this information, but not the strict formatting or extra guidance and friendliness!

A standard template

Update: we now have a template we use with the first-timers-bot that has lots of excellent wording and nice emojis to be extra friendly! Find it here:

https://github.com/publiclab/plots2/blob/master/.github/first-timers-issue-template.md

Good candidates to source from

We've especially marked some as fto-candidate issues if we think they'd make good first-timers-only issues, but haven't yet had the time to follow through with the formatting -- you can choose one and upgrade it: https://github.com/publiclab/plots2/labels/fto-candidate

Note: you need not be a coder to write this kind of issue, either! Much of this is just good formatting, context, and friendliness; for the parts about the actual fix, you can ask someone who's familiar with the codebase (like me!) to help out before finally labeling it.

Copy-paste that all into a new GitHub issue, and fill it out to describe the problem and the solution:

https://github.com/publiclab/plots2/issues/new

This template could surely be improved or refined -- please make any suggestions or ask questions in the comments below!

Sources

We learned about this outreach strategy in a talk by Gregor Martynus of the Hoodie project at a BostonJS meetup, and through further reading at firsttimersonly.com and up-for-grabs.net. You can also take a look at this post on the Hoodie project for some tips about what makes a great issue description for new coding contributors.

Read more Follow

community outreach gsoc web