GitHub GitHub Universe 2020: Developer - Open Source Communities, 11 Dec 2020

Previous Meeting

Next Meeting

⏯

youtube image

►

From YouTube: Building your community with GitHub Discussions - GitHub Universe 2020

Description

Presented by Neha Batra, Director, Software Engineering, GitHub

Calling all open source maintainers! Your communities have thrived with issues and pull requests. But sometimes you’ve had to get creative with how to engage with each other beyond code. With this session, we’ll explore GitHub Discussions and how the tool can enable you to connect with contributors on new ideas, help others without inflating your issue count, and recognize non-code contributions. We’ll give you an insider’s look at the beta, share learnings from maintainers at Vercel, Gatsby, Node,js, and others who have been testing out GitHub Discussions, and showcase the possibilities of what you can do to energize your community. We’ll even slip in a sneak peek for what’s to come!

For more from GitHub Universe 2020, visit https://githubuniverse.com

As always, feel free to leave us a comment below and don't forget to subscribe: http://bit.ly/subgithub

Thanks!

Connect with us.
Facebook: http://fb.com/github
Twitter: http://twitter.com/github
LinkedIn: http://linkedin.com/company/github

About GitHub
GitHub is the best place to share code with friends, co-workers, classmates, and complete strangers. Millions of people use GitHub to build amazing things together. For more info, go to http://github.com

A

Hi everyone thanks so much for that introduction and I'm part of the team that brought you have discussions. I'm really excited about talking about building your community with github discussions which, as of tuesday, is available for all repos and public beta, and so thousands of you have turned it on since then. This talk is primarily geared towards maintainers at github, but if you're, a collaborator, triager contributor or just someone who's curious about. What's in, what's investments, I'm planning to see.

A

So what I'm going to show you in this talk is a tour through each of the features on github discussions for each feature. I'll show you our recommended best practices and some cool examples of how other open source communities have used. Those features during the past private beta period, hopefully that'll, give you some ideas about what you might want to try when you're using github discussions for your community and of course I won't leave you hanging.

A

This release is only a beta, so I'm going to show you basically a little sneak peek of some of the work that we have coming up in the new year and I'll make sure that you know how you can give us feedback about what you like and what you'd like to have so before I dive in. I want to quickly talk about the open source ecosystem and why github discussions exist in the first place.

A

So this is an incredibly oversimplified cycle of what open source works looks like on github. So basically people use a feature tool or product. Then they notice an issue they file an issue and that work will hopefully get prioritized.

A

May be worked on, uh someone will open up a pull request, it'll get merged and boom, it's slated for a new release and it goes out into the world, and people use the new thing so already there's something missing, and um that is where the conversation lives and that's because it usually lives over here outside of the cycle, products, ignite ideas and facilitate conversations, and that conversation ends up in chat applications, forums, social news and basically sometimes github issues and as someone who used to work full time on open source products at github I'll tell you right now.

A

It's really difficult to manage both conversations and work within github issues and you've told us that too. You don't want someone writing in your to-do list and you want github issues to be a place of focus. We heard you. We want to keep q a and conversations separate from github issues, but we also don't want those to be completely detached either. Their relationship is important.

A

That's why we've added github discussions into the cycle. Github discussions brings the important conversations to the place you work without overlapping them, with defined prioritized ongoing work that you have in issues and pull requests, so you can think of github discussions as the living room of your open source community. So work with me, you have discussions is a place where people can come in grab a seat on the couch. Chatter, maybe get a new idea, maybe get inspired by that idea, and I don't know venture over to the kitchen and cook something up.

A

It's really clear that I probably selected this metaphor because it's 20 20 and I don't have a living room full of people, but I have found you have discussions to be a virtual homey place to interact with my community. The best part is that it enables non-code contribution pathways, so it lets people interact amongst themselves and help each other, and it also makes people makes it easier for the folks with questions to talk to the people with answers, be it maintainers collaborators if someone who's just been there before.

A

So, let's get started. Shall we? If you haven't enabled discussions, yet I'm going to show you how now so to start you're going to want to go to your repos settings page and then you can go on that default. Page scroll down to the features section and you'll see a discussions, check box waiting for you- and it looks like this. So you can click on set up discussions to get started, and this is going to take you to a pre-made template that we've set up for you. You can review modify it.

A

Maybe you don't want any of those comments in and then voila click on start discussion, and you have your first discussion now. It's good to pin important discussions like this one. So you can click on, pin discussion and then you can kind of choose a really cool color. I love the blue one. Obviously we're going to go with the octa cats. You can click on, pin, discussion and there you have it on your index page your first discussion now.

A

If you have issues that should be discussions, you can cover those individually um convert them in or in bulk. So if you wanted to do it in bulk, you can go here to the label section here. We selected the question label, obviously probably the best one, for that is a q, a category and there you go.

A

All you have to do is click that button and you're going to convert those from your issues over to your discussions, and you can see that over on your discussions page now, as I mentioned before, github discussions has been in private beta since may, which means we've seen a lot of really creative ways to get started. So I'm going to show you two examples about best practices that you can use.

A

A best practice is to customize even your first introduction exactly for your community, and so this is one that I wanted to show you, which is the pi stock community that took the setup template that we provided and they translated that also into chinese to introduce discussions into their community in two languages.

A

Another discussion that gets a lot of traction is the one where it's a welcome discussion where you can help introduce yourself. I think this is especially valuable for maintainers and collaborators to post in the discussion early, basically to set this tone and tell people how you'd, like your community to introduce themselves and what information you'd, like others to post in also so we've gotten started. Congrats.

A

Here's a map of what I'm going to show you for the main course of the talk, I'm going to be going through customizing categories, creating discussions, answering questions, recognizing contributions and your moderation options.

A

So, let's start with categories: every repository comes with a default set of four categories: general ideas, q, a and show and tell- but these can be modified. Only maintainers and admins can do that. And so what you're going to do is you're going to see that edit button only available to those people, I'm going to click on it. So when you get there you're going to see the categories edit page and you can click on edit for any category or if you click on a new category, I'm going to try one call it components.

A

um Obviously, I'm going to choose the avocado emoji, because I mean there's no explanation needed and I'm going to choose a description description so that people know which category to choose and what we're left here with is a discussion format.

A

Now the discussion format, you have two options: one is an open-ended discussion which is just for casual conversations and the other one is question answer. So that means that any discussion that's created in that category allows either the author or the maintainer or a collaborator maintainer, to select an answer for every discussion that exists in that category. So you can always go in. You can modify that later if it's working or it isn't working for you.

A

So here are some examples of what other open source communities have created for their categories. So the first one here is with nextgs you're, not seeing anything particularly unique in the categories here. But the interesting thing here is that in their ideas category they use this as an rfc, which means request for comments, and so maintainers often present their ideas to the community and they're. Looking for comments and to get reactions to what those ideas are, I really think that's like a cool way to utilize the ideas category.

A

The second example I have here is azure pl, so they have some of their categories in polish, um which makes sense for their community. The third one is home assistant and they have the accessibility and localization categories, which is important because it helps people with the expertise, find the discussions and they can help with right away.

A

Fomantic ui is our fourth example and they've chosen to use their categories in a more structured way to filter out the kinds of conversations that people typically come up for that repository and finally, gatsby js has a cool umbrella discussions. Category and they've been using this for um for the maintainers to open up discussions around topics like cash, clearing flags or parallel sourcing, and it's often with links or docs, or basically helpful information for the community, and it opens up this to the community for questions, bugs ideas or updates.

A

I think the most important thing about categories is that um you get to set the tone here to help the community know what to expect and where to go. It's like a map.

A

So, if they're a common area that you notice that comes up over time, you can always create new categories, or maybe you realize a category is seldom used and you can go ahead and delete it and don't worry when you go to delete a category if we notice that there's discussions inside we're going to ask you where you'd like to reassign those discussions um and take note that you do have a maximum of 10 categories that you can create.

A

Okay, now that you have the right categories, it's time to walk you through that new discussion flow once more, and I'm going to point out a few things that happen after you: click that shiny green button. So the first thing that I want to point out is that you can see in this drop down. That's where your title and your description show up.

A

So when you're creating your description, you want to make sure you're gearing it towards your user, and the second is that once you post a discussion on the right hand side here, you can see a piano of the things that you can do to moderate the discussion and that's only available for certain roles. And finally, when you pin discussions, I want you to know that you can pin up to four discussions.

A

My personal recommendation is that it looks way cooler if you switch up the colors and the patterns of the pin discussions to give it a more dynamic feel, and once you have a pin discussion, you can always go back and edit it you can unpin. You can even reorder the all the pin discussions all together as a maintainer.

A

You can also go back and edit anyone's individual discussions for someone else. That's posted to help things become more structured and organized.

A

So here's an example here where snowpack has uh used the a pin discussion as their change log, and so it's kind of pinned at the top.

A

You can see that fred's got some spot-on gifs here and what I love is that each comment is a new version and it details and it allows people to easily reply with thoughts or words of thank or encouragement another one that I think is really cute is that react hook forum has a community member, they a community member, went in and they congratulated the community for an award that they received, which I thought was so sweet and charming, and it's really appreciated, and so of course the matingers went back and they pinned that discussion.

A

Here's a q, a example for you- and you can't exactly see it here, but in this thread the author had asked about getting a tile with spaces between images and global borders, and someone had posted an answer within reply and within those replies you can see here. Multiple people are jumping in to help make that answer more helpful and for this example specifically, what had happened was that two people had posted answers and they're really helpful, and so there's this really awesome dynamic.

A

Where the original author of the post was like, I don't know which one to pick you both have been so helpful and then both uh responders said, like don't worry about it. It's just about like getting the right answer, and I just felt like this was a really adorable uh example, because it's what you would see in a healthy, open source community- and I thought that was wonderful.

A

So this is another example. It's an example of where a maintainer saw a question realized. There was a legitimate bug. They opened an issue for it and a pr for it and they merge and deployed it when they came back. They followed up and they said like hey. This is corrected and it was in the same day.

A

So this is a really cool way to kind of uh connect, both the discussion and the issues and have that duality work, and they marked that as the author marks, that as an answer so that anyone who comes back will see that that is now fixed, and this is like in a new version.

A

Another example I wanted to talk about was that 2020 is really real and, of course, all the time there are cases where maintainers aren't going to be able to keep up with their community and it's totally okay, to open up a discussion explaining that you can pin that at the top. And that way your community knows what to expect, and um you can kind of see that people have reacted really well to this discussion.

A

So let's get directly into the mechanics of marking an answer. So anyone with triage plus access or the author can do this, and this is kind of what it looks like when you find an answer to a question. You can click on the check box and a great box will appear- and you can say who marked the answer and it'll be recorded, so you can even see who marked it right underneath, and so I guess brooklyn was asking for the best guacamole recipe here without anyone else responding. She marked her own answer.

A

I don't actually see this happen too often, not many people are asking for guacamole recipes, but um this is kind of an example of what you can see and I'll give you more realistic examples now.

A

So here's an example where an author might mark their own answer because they asked a question: they did some research and they went back to answer it, um and so you can see that it'll help everyone else who comes across that question and here's an example where the maintainer knew the answer to the question, because it was about an existing bug, but they even went into the replies and they helped that person get access to where the pr was to get the fix up front.

A

Now you can see an answer uh was marked here, um but I think this is more for humor, and so it gets bonus points for creativity. So you can see that uh someone that the maintainer had asked is adonis five uh production ready and they responded to their own answer. As yes, I thought that was really cute, and so I wanted to point out the example.

A

Now we have all the tools that we need to manage existing discussions. Let's talk really briefly about some enhancements. We have to improve the community's interactions and first things. First, you can see right here, there's a leaderboard on the right hand, side and it shows people with the most answered discussions.

A

So when someone's answer is marked as an answer, it might show up in a leader board, especially if they're in the top eight but you'll also see that data gets added to their hover card. So in the middle here you can see when you hover over someone's name. It tells you, for example, robin has answered a few discussions in the past week but 36 in the last month, and then, if you were to go on their profile, you'll see a total count, so they've answered 116 overall at the time of us taking the screenshot.

A

I thought that was pretty cool. This is the kind of information that you can use to understand who's particularly active and might be a candidate to become a triager or someone with write access one day, and we actually have a story for that for you.

A

So next js was an early adopter of github discussions and they kept noticing that james mosher was one of the people who were consistent in answering discussions, and so with that data that was able that they were able to see they basically went and approached james, and they asked him if he wanted to be part of the community and he became a treasurer for nextjs, and he said yes.

A

So this is a great example of how important non-code contributions and valuable they are how important and valuable non-code contributions are and how the maintainers can leverage that leverage that information to bring people into the community. Even more so we got his permission to tell the story and when we asked him about it, he shared how he remembered really vividly what it's like to start coding and have a ton of questions and it's his way of giving back.

A

So he said that answering and discussions allowed him to learn a ton by digging into the next code, nexus code base, and he wanted to make sure that he was accurately answering those questions, and you can even see that this comes with a sense of pride, so you can see on his profile he even added it to his readme, and so you never know who might emerge to build the community and thank you for letting us share your story james.

A

Finally, I wanted to briefly talk to you about what you can do with triager write, maintainer and admin permissions and as far as discussions go, people with write maintain admin. Access can basically do the same thing with two exceptions, so um people with maintain an admin access can enable discussions altogether from the settings page and also they're the only ones who can create and edit categories, but otherwise they have the same permissions. So I'm going to show you what you can do with triage roles and write roles.

A

So when you're selecting people in the community you can know which ones to give so I've got three spots to point out. So the first one is the in the kebab for each commun discussion, comment or answer or reply. You can um click on the kebab, and so people with triage plus roles can hide comments, um replies, etc, and people with write plus can actually go ahead and edit them now, on the right hand.

A

Panel there, you also have a few options, so triagers plus can lock a discussion and people with write, plus access can transfer it, pin a discussion or delete it, and in this example, you can kind of see through the events that brooklyn went in, they locked the conversation, and so people with that access can also a triage plus access can unlock it.

A

Finally, in the top right, you can see that there you can, you see a little gear icon next to the category, which means you can change the category, um so that is for people with write, plus access, and if you ever another thing, that's really valuable to know is that if you can convert, if you convert an issue to a discussion, it carries over the moderation as well, so in case you're curious. This is what it looks like one.

A

This is what a hidden comment looks like and that's basically it that's what you have so we talked about getting started categories. New discussions, marking answers how you can use the information, the site to provide recognition and how to moderate and keep the community healthy.

A

Now, github discussions is still a work in progress, it's genuinely a beta product and so we'll be iterating on it to get it to ga after the holidays and here's something that some things that we're cooking up so the first one that you've probably already noticed is that if you're on the beta for ios or android, discussions is available in the github application, if you're not on the beta.

A

Here's a sneak peek of what you'll see when it comes in at gas in the new year, so you'll be able to open, moderate mark and reply to discussions in true async fashion.

A

The second thing I wanted to give you a glimpse of is up voting, so we're still playing with the feel of it, but you'll be able to you've been able to do this on the universe, repo and you'll be able to soon do this overall, we're still playing with it. It's in the features in private beta um to be able to upvote both discussions and comments, um so that'll also be feeding into a sort which means that you'll be getting the most valuable discussions sorted up top and that's not all.

A

uh Just trying to get my uh oh there we go cool, so that's not all we have a long road ahead and, oh, no, I think, there's a lag.

A

Oh no, there we go okay, cool, so we've got a long road ahead and to give you um to give you the product that you need to build the community even more successfully. Here are some of the things that are on our roadmap in case you were curious and the best way to hear about upcoming features is, as they become available, is to give us feedback and to come and find us in our open source repository. So for today you can go to the universe one. This is a short link.

A

It'll, redirect you to the github universe, 2020 repo I'll, be there right. After um and beyond, you can go to the github feedback repo, and you can talk about what you like about discussions or anything that you see on mobile now as far as finding out the latest features, um your best bet is to watch the roadmap repo or to go and follow the twitter account gh, changelog and we'll also do our best to reply to comments or for requests that we've seen in the feedback.

A

Repo last thing this was a huge undertaking and here's some of the hovers that were involved. So you see you see them around. Then um you can see that if you see them around in the feedback, repo or anywhere else make sure to say thank you and that's it. That's all I have for you. Thank you so much.