Cloud Native Computing Foundation KubeCon + CloudNativeCon Europe 2021, 14 May 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Build your Contributor Pipeline - Carolyn Van Slyck, Microsoft & Josh Berkus, Red Hat

Description

Don’t miss out! Join us at our upcoming event: KubeCon + CloudNativeCon North America 2021 in Los Angeles, CA from October 12-15. Learn more at https://kubecon.io The conference features presentations from developers and end users of Kubernetes, Prometheus, Envoy, and all of the other CNCF-hosted projects.

Build your Contributor Pipeline - Carolyn Van Slyck, Microsoft & Josh Berkus, Red Hat

Would you like to attract new contributors to your project and grow your contributor base? CNCF SIG Contributor Strategy has developed best practices to improve your contributor pipeline and can help you adapt them to your project's needs
Attract new contributors to your project with good first issues.
Create onboarding materials, such as a contributing guide and onboarding tutorial, to guide their first contribution towards success.
Improve the contributor experience, encouraging people to join your community and stick around after their first pull request.
Publish a contribution ladder so they see a path from new contributor to maintainer and other project roles.
Find a balance between your time commitments as a maintainer and helping new contributors.

Whether you are a new sandbox project or an established graduated projects like Kubernetes, you will come away with a realistic actionable way to sustainably grow your community.

A

Hello and welcome to build your contributor pipeline with cncf sig contributor strategy uh and josh and kerala uh we're here to explain something that a lot of projects have been asking about lately, which is how do we get contributors? How do we get new contributors for our projects.

A

My name is josh burkus, I'm a community architect at red hat in the open source practice office, where I work on the many cloud native projects that we support at red hat, plus a few that aren't technically supported by red hat. But I help in my role with cncf anyway,.

B

I'm carolyn vanslick, I'm an engineer at microsoft and I work on the cncf sandbox project porter.

B

So before we really get into advice, and things like that, I want to just stop and make sure that we're being intentional and understand what we're hoping to get out of this. When you say you want to build your contributor pipeline, what are you trying to achieve? Do you want to create a community around your project? Are you trying to find that next special maintainer, or are you looking for maybe adding more people who have diverse skills and perspectives that your project is lacking depending on what you want to do?

B

This could be a pretty big time investment. So you want to make sure that it's not just you trying to figure this out and welcome new contributors to your project. You want all the other maintainers on the project bought in and understanding what your game plan is.

A

So before we get into attracting contributors, so let's think in general about where contributors come from new contributors for open source projects. Why do they join to begin with.

A

Usually, though, we've got three sort of different groups that come to projects with the goal of contribution or participation. The first group that people are the most familiar with is individual users. These are people who use your project or they use your project to build other things, and sometimes they're just really excited about the project. They want to be a part of it. They want to participate other times. They have something specific that they want to add or to fix, that's broken for them in their use case.

A

Usually, these are what we call power users who are using it in production who are using it in some very advanced way.

A

However, in the cncf we actually get a lot of a second kind of user, which is what we call corporate users, which means that, rather than the individual, using your project, their company uses the project and depends on it. And for that reason the company has assigned them as an employee to work on the project, either again to add some functionality or to fix something that specifically matters to the company or, if you're extremely lucky, to maintain help maintain the project in order that the company can depend on it long term.

A

Now, a third group that people often forget to think about which is bad, because this group is unique in a lot of ways, is what we call learners. Maybe they want to learn the programming language? Maybe they want to learn the field of technology that your project is in, maybe they're about to graduate school and they want to beef up their resume. The nice thing about this is these people will contribute to areas of your project that are fairly non-commercial because they don't care, and so you should cultivate them. If you can.

B

So, let's think a bit about what type of user are you focusing you know we're thinking about? Where are they coming from? What are their motivations?

B

So what's the pool of people available to us, the most obvious, maybe the first place you should look for if you haven't already, is look at your existing user base. These are people who are opening bug reports with you, they're already engaging, maybe in slack they're, pretty much, maybe the best well to go to to find new people. But if you're trying to look even further, you can consider recruiting people who don't actually know your project at all. uh The learners especially fall into this group.

B

Another thing you can look at is: are you lacking contributors with specific skills? Like raise your hand, everyone needs a tech writer. uh You probably need someone to help. Make your website look. Look right, create concept, art uh diagrams.

B

You know someone to help with that roadmap for project management and what a lot of these have in common is that they aren't code contributors, they're, not coming to you and submitting a poll request. You need to go to them and think about what you can, what they can bring to your project and make sure that they know that it's welcome, so people can write documentation.

B

They can give you user stories and feedback on your roadmap and designs write a guest, blog post, explaining how they're using your project a lot of these things are gold, but people won't give it to you. Unless you say it's welcome now, some people may be looking for that unicorn an experienced maintainer, who has already been a maintainer on another project, and you need somebody who's. You know a superhero essentially to help you out, but that's not even worth looking for these people, those type of people already too busy and have their own projects.

A

So once we've identified what kind of contributors we want to attract and where we're going to be contributing them from, we actually need to construct uh a framework um called the contributor framework in order to look at how we're going to interact these people- and I find it's useful to divide these up into enablers and blockers enablers- are things that help you attract additional contributors.

A

That is things that, if they are present in your project, if they're good will cause more people to show up and help people who have already shown up to stay, and you can further divide these down into things that are what we call low investment for things that are high investment. A low investment example would be hey, creating contributing that md file or having a contributor forum right.

A

These don't take a lot of your time and energy to create, and yet they really do help people become and stay a part of your project and then there's a second group of things that are much more high investment, but often also pay dividends in being really strong contribution.

A

Enablers, like, for example, if you create a very detailed contribution tutorial going through every step of the way of oh hey, you want to add a feature to my project, um then that will enable your code contributors to self-start without needing to have one-on-one mentoring in order to contribute stuff and thus for you to get more of them and for them to be more productive once they do join. But creating that kind of a tutorial is hard and it will be a huge time commitment from one of your existing people.

A

One of the other things that's often overlooked as a very simple enabler, which is low. Commitment is uh recognition, so when somebody does contribute make sure they get noticed in some way, um digital badges swag, uh you know here. Actually I've got you can see right here. This is my kubernetes contributor summit, shanghai t-shirt, so special contributor, swag public thank yous and public contributor listings people actually care a lot about being recognized, even if they don't say that they do.

A

Now there is a bunch of things that can prevent even your best intention contributors from contributing to your project, and these are things that you want to try to eradicate from your project. So they don't ruin your other efforts, and this is things like really stringent contributor license agreements or community license agreements as opposed to a dco not having any visibility into the project in a variety of ways: governance uh rights on repositories, tests, um open sourcing.

A

Your test framework is hard I understand, but on the other hand, somebody contributes, they get a bunch of pre-submit test failures and they ask hey. How do I troubleshoot this death failure? And you tell them well you can't, then that contributor is blocked until one of your existing people gets around to troubleshooting it for them, and that's a bad experience for them, and it's a bad experience for your people.

A

Now one of the biggest things about enabling contributors is communication and being as open as possible about communication. So if you're having a strategy meeting or a developer meeting or a stand-up or whatever, that should be in the open external contributors, you know, even if you have it's a company sponsored project external contributor should be able to join that public contributors should be able to join that meeting if they want to now a lot of the times they they won't want to.

A

um But they need to know that it's there and those meetings should discuss things like your strategy and your roadmap and your plans.

A

Things are ideally also published in text because you want to make contributors new contributors, part of planning, for the project which both makes them feel included and make sure that they don't spend a lot of time on things that are out of scope for you also, please, please, please don't make attending things like daily meetings mandatory for contribution, because that limits your contributor pool to people who are being sponsored by companies to work on the project full time.

A

Now, when we've sort of been over, this we've looked at the various ways you can communicate and there are some things that reach more people for less effort than others and- and that starts with anything that you can have that's both written in asynchronous, so, whether it's your documentation or a mailing list, or a blog or a discussion forum of some sort, if it doesn't require synchronizing time zones and if it's written, so people can refer to it in the future. That's going to reach more people more easily.

A

After that start looking at an open developer meeting, because it's something you would hold anyway and then move on to more very contributed, targeted things like office hours or end user forums, right that are just specifically contributors. One of the mistakes we see people making is they create this community meeting.

A

That is specifically just a community meeting and then it doesn't work because they really don't have any content for it and that should really be handled by things like your blog.

B

So we're going to list everything that you can do to bring in and keep contributors in your pipeline, but I want to make it clear that that's not everything you should be doing, and you definitely shouldn't be trying to do all this at once.

B

Considering your project size, how many people you have to support any uh recruiting efforts and then pick one try it see how it goes and and focus on tasks that make you scale anything that involves one-on-one mentoring, live things, synchronous things all that save for later start with all that written communication, for example, and then over time you know you can add more because what's important to understand here is that recruiting and growing your pipeline is not a one and done thing.

B

If you add three contributors over time, they're going to eventually leave your project will change. You need updated documentation. Your recordings get old, you're, always going to be doing more things so commit to a small amount of work and find a way to be able to do it every couple months and refresh and and make another uh recruiting drive essentially, but it is not a destination. You're never going to be done with this.

B

So let's consider how you let people know that you want new contributors. The obvious place is the contributing guide, but there's actually a lot of other breadcrumbs. You should be putting out there so that people know that you're actively. Looking for more contributors, the first place, most people are going to see your project is actually your readme.

B

So that's where you're going to want to say: hey, we want you come join us another place that I've seen people do it is they have a dedicated page on their projects website that talks about wanting contributors and kind of walking people through it.

B

Another way to signal that you're looking for people and this one's kind of fun, because you get a lot of people for free, is labeling your issues as good first issue and help wanted, because other projects hackathons things like that, hacktoberfest we'll link to all the issues in github and go look for ones that are good. First issue look for ones that are help wanted and you can actually put up on your contributing guide link to these and give people ideas for where they can get started.

B

Another thing is: if you're, given a talk, if you're doing a webinar anytime you're there pitching your project, let people know that you want help.

B

So I mentioned your readme. This is an example from my project. Porters uh read me here and like we're unabashedly like we need help, come contribute work with us and we link people to the new contributing guide. So that's focused just on helping people get started with the project for the first time, and then we also call out to our existing contributors. Again. Recognition is important. Let people know that you're going to recognize their contributions.

B

I also have a page on my website that says: hey. We want you to work with us for a lot of people coming to this. They may be unfamiliar with what your project is so lay that out like point them to other places on your site point them to tutorials. Let them know where they should get started. Let people know what are the types of contributions you're going to welcome, especially if you're open to non-code contributions and let people know, is there a path to becoming a maintainer.

B

If you do this basically put up front all the recognition and rewards for working on your project into these documents,.

B

Now, in your contributing guide itself, it's kind of doing double duty here, right, oftentimes, you're, talking about build tasks, how to do certain things. What are your build scripts, but at the very top, what we like to do is let people know again that you're looking for contributors, people will find your contributing guide, because someone will link to it and say this is the best way to get into contributing or every time you submit a pull request. It'll- probably link to it at the top.

B

So you want to just always make sure that welcome mat is there and let them know the ways that they can contribute and then, as always, it's welcome.

B

So let's talk about labeling real quick. There are like common accepted default labels like if you make a new repo, you probably have a help wanted. You probably have a good first issue label, but there's so much more to making it workable and your goal should be. If someone picked up this issue on the weekend, could they complete it without pinging people on slack getting lost asking for help? Is there enough context in the issue that they can actually just accomplish? It help want it is kind of a special label.

B

It does double duty, essentially one it's great for people who are newer to the project and kind of calls out issues that are going to have enough information for them to do things, but on the other side, they're also really good. For saying this requires a skill set or a particular knowledge that we're lacking in the project, maybe you're. Looking for someone who's a tech writer to help with docs you're.

B

Looking for someone who has specialized networking knowledge, something like that oftentimes, even though they're new to your project, they're, not new to the domain, and so they can tackle more difficult pro issues than you would have expected.

B

Good first issues is a subset of help wanted and the idea is we're really removing all the barriers to entry, we're making sure that we completely spell out. This is how to do the task, give examples to the code like link directly to github. This is what you should change. Go here, one two, three: four: what should you be doing?

B

Where is the test if it doesn't have a test, and you need to kind of make it test out of thin air? You either need to link them to something they can copy. You know and kind of model off of, or maybe it's actually not such a good first issue.

B

Yet here's an example of a good first issue, and what's here doesn't matter, but what you can kind of see at a high level is: I have links to the code that needs to be changed and I've step-by-step instructions saying how the change should be made, maybe any background or motivation. So they understand why they're making this change and then where they can add their tests to.

B

Now I've had a good first issue open on my repository, probably since day one from three years ago, and I'm never ever going to close it, because new contributors who are coming to my project have a perspective that I will never be able to have again on my project, which is being new to it.

B

Not knowing the right way to do everything, not even knowing the domain, and this is the type of perspective that you critically need in order to constantly vetting your project and making sure that you haven't left gaps in both your new contributor documentation and and honestly, your new user documentation.

B

So it's kind of cool as a new contributor to be like I'm in the best possible position to do this task so make sure they always know that we want them to open pr's or just ping. You any way they're willing to give you this feedback about what it was like to be a new contributor or a new user user on your project. Make sure you get that feedback two one.

B

Now, let's take a look at you've, attracted someone to your project, they're interested in contributing you're, going to need to teach them what it takes to contribute and what's involved for various things, there's the obvious which is setting up your environment right and we'll get into that. But less obvious is telling them what your project is and how to use it.

B

Thinking back again to those learners, they may have never used your project before they may not be familiar with cloud native, so any videos or content blogs doesn't matter something that's going to get them up and running with your own project before they try to make a first contribution is going to save you, a lot of heartache, reteaching people things and it's going to help them feel more productive from day one and in general, you're going to want to focus on your like the experience for that first pull request and and how you want to handle them and how you want to handle this.

B

Some people like to take this and encode it like in my project. We actually say all reviewers you're going to look out for new contributors. You're going to do x, y and z, but it could just be something informal that you talk about with your other maintainers and go. What do we want? This experience to look like for a new contributor.

A

Now, there's different ways that you can actually do this sort of intake process and, like we said before, I want to say first of all, the first way that you should work on is the sort of text guide version of this. It's going to be the most generally accessible, it's accessible around the clock, it's much easier to maintain and keep current with your projects, contribution processes and code and documentation.

A

Once you've taken care of the text version, then you might want to consider having some online videos, because some people are video learners.

A

They learn better from videos, but if you want to gonna, do that having a lot of short videos is better um from a maintenance perspective, nothing else right, because things will change about your project and it's a lot easier to re-record, a single three-minute video than to have to re-record that 90-minute full tutorial sort of the last thing you should do the thing you should do only when you feel like you are sort of fully staffed up and you've done.

A

All the other things is the sort of in-person workshop um because attractive as that is when you're having say a project summit. It's actually the most resource intensive to reach the fewest people.

B

This was a suggestion from charles in from blakerd, and I took this and ran with it for porter, and I found that this was actually one of the most valuable things I could have done for my own pipeline, which is, I wrote, a contributing tutorial that says from start to finish.

B

What does it look like to change my project to get set up test, the code etc? And the very first thing on here again is: I want to see contributors, try the project and understand what it is like. They've definitely run it before they submit their first pr. I've got a number of first pr's before where it's like you can tell. They never actually ran it.

B

They figured out to code the change and I feel like you're, not doing anyone a favor there we're here to learn we're here to become better at these things, so make it clear up front like try. It learn it give us feedback on it um and then walk them through. How do you set up your environment to build the code? How do you check it out if you have any specific, build tool, recommendations?

B

Most projects have signing, for example, like a dco. Do not assume that someone knows how to do this, or this could turn into a blocker for you, even if it's something that could be easily done document how to do a dco, how to sign your commit and then also oops how to fix it when you forgot to sign something otherwise, things I like to look at is how to build the code. Try it out both manually and through the command line tool or an api.

B

Whatever makes sense for your project and then do an actual change like porter is a command line tool. So we always have someone make a sample command that like prints, their name, for example, show them how to test their changes in general and then celebrate. Have them tell you when they finish the tutorial, because, again closing the loop here remember that they have the best perspective on improving these docs talk to them after they've done this, and you're probably going to find something new that you need to change. Probably every couple contributors.

A

Now one of the things we talk about in terms of contributors is you don't want to just get new contributors, but you want to advance them right, because one of your goals eventually is to have more maintainers for the project, because that's the only way that the project is really going to grow and moving from new contributor to maintainer goes through a series of steps that we like to call the contributor ladder and for this contributor ladder to work.

A

It's something you actually want to publish the different sort of project roles and what the qualifications for each are and what the responsibilities of each are. So uh you know add that in consider some things that you maybe don't have yet as a way of recruiting people like, for example, maybe you don't have a docs maintainer, but you would like to have one well putting that role in your contributor ladder is an opportunity for somebody to say hey.

A

I could do that um also it's important to write this down on paper, because a good way for you to agree among all of your existing contributors, how people earn trust and how they advance, because, if you're having that argument in with the contributor at the time that they want to advance it's a bad experience for everybody, decide it in advance.

A

Now we have examples of this. We just finished the contributor ladder template which is uh part of our project templates, but in advance is exactly very simple right. We have contributor and how you become a contributor maintainer, how you become a maintainer admin, how you become an admin depending on the roles right. Other roles might include reviewer, docs, maintainer organization, member, for how people get credentials on github, and we have some examples in the template of how you define those things.

B

So we've, given you a lot of examples and you've seen screenshots of what various documents are, that would be really helpful to have in your project now as part of our sig we've created templates, where you can just clone this entire repository or cherry pick files that you think would be useful and it covers things like the readme in this contributor letter, which you may not be familiar with.

B

We also have created guides now, basically, all the information that we've given you here in this talk, you can find in text format in some of these long form guides on our website. For example, the contributor playbook will go into details on how do you find and recruit people into your project and attract them, whereas the contributor growth framework is real stories from maintainers of successful projects and what has worked for them and reflections on? Maybe what hasn't worked so well too.

A

So if you have other questions or if you are excited about this or you want interactive help on advancing the project attracting contributors, this is what sig contributor strategy is here, for uh we have two different meetings for the asynchronous option. We have two different meetings, uh one every first and third thursday of the month at 10. 30 am pacific time. uh Alternating meetings are maintainer circle meetings, uh the other meetings are general and you are welcome and encouraged to bring your project in your particular problem and put it on the agenda for that meeting.

A

That is completely invited for specifically attracting contributors. We have the contributor growth working group meeting every second and fourth tuesday, at 2pm specific, and that is for more contributor growth problems any way. You're welcome and around the clock. You can join us on cncf slack um in the sig contributor strategy channel.

A

Now we will move on here to any questions you have during the session.