GitHub Demo Days, 15 May 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Discoverability and why it's particularly important in #InnerSource #DemoDays

Description

2:03 - Program Start
4:15 - What makes #InnerSource successful?
6:10 - What is the discoverability problem?
7:26 - Repository visibility controls
10:29 - The importance of descriptions and topics
13:19 - Building a Community of Practice
18:18 - Write that blog!
20:38 - Internal comms
24:47 - #InnerSource portal demo
33:39 - Enterprise showcase - an active list of subject-specific projects
37:29 - Using Codespaces to modify the collection
41:18 - Getting contributions to your projects, README
43:46 - Contributing.md
44:48 - Template files
45:18 - Issue templates
46:29 - Pull Request templates
48:14 - Hackathons
49:25 - Being a good maintainer
51:53 - Codespaces

Practical and specific steps for making sure that your #InnerSource efforts gain traction within your organization. Make your projects easier to discover, contribute to and use. Use momentum to your advantage by building an internal community of champions. Matt Desmond, Solutions Engineer and Chris McIntosh DevOps Engineer talk through why discoverability is key.

InnerSource commons: https://innersourcecommons.org
Resource links from the session: https://github.com/demo-days/innersource-discoverability

A

Hello, hello, everyone, hi chat, how's. It going welcome to demo days hello to folks from serbia, hello to folks from india, hello from all over the world. I see you all valencia, I see lebanon. I see germany, brazil, I see france, I see more india, hello, nice, to see everyone another busy busy friday. I hope you're doing okay wherever you are in the world uh good morning, good afternoon, good evening, good night.

A

um Last friday we introduced an idea of inner source and how it both learns from open source as well as is distinct from open source itself. Today, we're going to zoom in on discoverability and why it's a particularly relevant challenge for any inner source effort. I'd like to introduce our guest for today, matt desmond uh solutions, engineer and chris mcintosh.

A

Hello welcome gentlemen, also, if you are watching this, and I think that your organization would benefit from a private demo or walkthrough of your specific use case feel free to use the qr code in the corner to book a meeting with us with that said, matt and chris take it away. Please.

B

Hey everybody uh yeah, like aj, said this is a follow-on to the great stream that we had last week talking about uh what is inner source so with us today, we've got matt desmond here, solutions, engineer from github professional services and myself a devops engineer also with github professional services.

B

We're going to be uh recapping kind of what makes innersource successful kind of the great presentation last week uh from there we're going to define what the discoverability problem is, so that we're all on the same page uh and then we're going to talk about how we can solve that problem and how promoting contributions can help solve that problem.

B

So what makes inner source.

B

Successful, uh creating a culture of sharing is kind of the prime uh prime candidate for making a successful intersource switch, uh making sure that your uh organization as a whole knows that you value uh contributing contributing to each other's source code and borrowing uh code from each other. uh You know preventing code reviews where possible and sharing ideas with each other, um and that is often like the hardest barrier to overcome uh after that, getting an executive sponsor.

B

If you do not have top-down support for uh creating your inner source push, then it is likely dead in the water, and it won't get very far as priorities shift and other things come up.

B

Determining a clear message: kind of figuring out what this inner source push and your organization is going to be and how it's going to work, making sure that everyone involved and everyone evangelizing it is on the same page- is an important step and this inner source commons link here that they shared last week is a great a great resource. It talks about communities of practice and all sorts of things.

B

I believe we will be going back here later today in the deck as well determining what success is for your organization uh and how to track. It is important, so figuring out uh what in your source that your organization is going to look like and how you will know that you're successful and how you will know how to iterate on that success. You can improve it further, um and I think uh this is the link from last week. I believe.

B

uh From the conversation last week, so this should talk about uh what they went through uh in the one last week. So what is the problem.

B

uh Intersource discoverability uh finding new projects is hard uh if you are at a large organization with hundreds or thousands of repositories.

B

How do you know, which is the right repository or the right project, to look at to find if your solution, if what you're doing has already been done, um the larger the organization, the harder it is? uh If your organization has a history of uh uh doing things in private, like many of our organizations, do this makes it more difficult uh that goes back to creating that culture of uh sharing.

B

So today we're gonna talk about how you can find new projects, how you can uh kind of encourage that culture of sharing, so that your inner source push is going to be successful.

B

So how can we solve this problem? How can we get our developers and everyone else at the company talking to each other and using each other's source code and documentation.

B

To start with, we want to talk about something as basic as repo visibility, so many times in your organization, when you create a new repository uh you're going to default, to creating it as private.

B

uh There are many reasons, historical reasons why this often happens, but uh one of the first steps you can do is just change your default repository visibility in your organization and say we want everything in our organization to be internal by default, unless there's a real need for it to be private and secret uh or potentially, if uh that is not quite the right solution for your organization, since, of course, you know one one size does not fit everybody, then uh perhaps taking a team based approach and saying everyone within this team or this business unit, everything they create.

B

Everyone should be able to see that way. Everyone working on the same sorts of things can kind of see how how everyone else is solving these problems, um and, like I mentioned this, doesn't mean that everything has to be open uh even at github. Here there are many repositories that I don't even know exist because they potentially have secret data in them.

B

Although you shouldn't be keeping secret data and source code generally or for various other reasons, um so you don't need to have every single repository open to the to your teams, but uh changing that default visibility to kind of encourage everyone to open things up to each other, and that is a very uh large hurdle to cross at first. You know letting your team or the world know how you write code.

B

You know letting everyone see your blemishes as you write bugs and fix them is kind of a scary thing to do at first, but it is a very good first step.

C

Yeah and just to add on to the repo visibility piece um when we're talking about base permissions, we're talking at the enterprise or the organization level, within your github enterprise, server or github enterprise cloud, where you're actually able to identify what the base permissions are for every user within the instance. That way they can either have like a read. So they have access to all of the public and internal repositories within your organization or organizations, uh or you can set it to write. um You can also.

C

As chris mentioned, you could go with the team approach, or maybe you have something like an all github users and then maybe even just like specific business silos or business units um and then being able to provide access to repositories based on what teams they're in uh it just makes it a lot easier for people to find repositories across like your larger organizations and even if you're, a smaller organization.

C

You know people start creating repositories either to test things out or you know, as new projects come up uh the number of repositories that your orgs might have starts to scale pretty quickly. As you start, getting work done.

C

Yeah. Definitely.

B

All right next, we'll talk about some features that uh github has in the repositories themselves. That kind of can help uh individuals or teams understand what your repository is like, how your project uh solves things. uh These would be the description, the topic and the topics.

B

So if we look at collected twice, if we look at adam's about section and their topics down here, we can see. We've got a very uh short description here. The hackable text editor. So we know immediately that this project is going to be something that will let us write text to the screen and if we see the uh topics that they've added down here at the bottom, we have. What is that seven different uh different topics that this could fall under since atom is an electron app.

B

It's there electrons written in javascript, that's there, etc, etc.

B

And if we look at visual studio codes, it is very similar. The description here could probably use a bit more descriptive bits to it. But again it has the topics down here and a link to the web page that can help you get more information.

C

Another thing to think about when you're using say repository, descriptions or repository topics as well is if your project started with, say like a code name. uh For example, there are different features that have been worked on at github that have had different names. uh One that comes to mind is like team. Rainbow skate worked on the um suggested changes feature within github pull requests uh so that initial repo was started as rainbow skate uh that doesn't necessarily translate long term to uh like a description of what that actually does.

C

So they change the repository name, something along the lines of like suggested changes, and then you know the description match that, uh but within like the topics of that specific repository, they were able to add rainbow skate as one of the topics that way.

C

If someone remembered that that feature was shipped as rainbow skate but didn't remember what it was actually for, what it was actually doing, uh they'd still be able to find it so by modifying either the description of the repository or the topic you're, just providing other avenues for the search results to find repositories within your organizations again, leading to like greater discoverability of the different features and functions and apps, and whatever else you're working on within your organizations.

B

And one thing you mentioned: uh you can rename repositories if the scope changes, if what it's doing is changing slightly to be more broad and the same goes with descriptions and topics all here that can all be edited as your projects evolve and make more sense.

B

uh So next we want to talk about communities of practice. So, uh if you're not familiar with a community of practice, it is a a group or a meeting of like-minded individuals that discuss and evangelize uh their uh their topic. So in this case uh we're we're talking about a uh inner source community of practice. So it would be uh your your initial group of uh stakeholders that are eager to get intersource set up and going within your organizations.

B

If you go to opensource.com and we'll link this here in chat, it is a great place to help you get started, but uh the bullet points from those uh from those blogs is basically, uh you want to find a sponsor so again similar to how your uh community of practice work or sorry how your uh inner source push works, that you want to have support from like the executive level, if that makes sense to your organization, because uh while this will provide benefits down the road you will have to, you will need to spend time doing it and you need to uh get support to spend that time, or else uh it won't go anywhere.

B

Next, you have to determine a clear mission for your community of practice, so inner source itself is quite broad, so uh picking kind of your goals for your community of practice so that you can figure out again what success criteria is and how you're going to push forward this effort inside your organization.

B

uh So so perhaps the uh the mission could be to uh set up an intersource portal so that everyone in your organization has one spot to go uh investigate what projects are out there.

B

Next, you need to build your team, and perhaps these two could be entertain changeable, which comes first, but uh basically you need to find the people that are really engaged and eager to see this uh to see this through and work with them to get this set up.

B

So you want to find a core group of individuals that are wanting to see inner source and help the company or the organization and get them to work together.

B

uh The next one select your document source so wherever you are storing documentation, whether that is in markdown files in a repository or any of the other third-party software, you want to make sure that everyone is writing the consistent documentation in one spot and linking everyone to that same spot so that everyone knows where to go, to get information about uh about the community of practice uh and finally communicate so open up your uh slack or teams or whatever chat channels and make sure that people know you're available and make sure that you're, not just talking to the people that are super engaged right so make sure you're advertising your community of practice meetings with others channels.

B

You know: don't uh don't spam everyone, but letting people know that your or your uh community of practices out there and eager to help people get started with this. Inner source thing is a great way of getting more more people involved and more projects opened up for the uh organization.

C

Yeah and to add so like with the selecting your documentation source, this is also a really easy way to get started with inner source within the organization, because you can start letting getting collaboration across your organization uh from different people that are interested in like say getting a repository set up uh to start intersourcing across teams. uh You can also you know you might need to mix and match your documentation sources.

C

So, if you're using confluences like your main form of like documentation for internal projects or just internal information, uh you can still link out to like say a template repository on github that has um readmes that are set up, or you know other files that we're going to be talking about later. That make it easier for people to start working within like a repository from like an inner source mindset.

C

But it's just important to kind of use the tools that are at your disposal and making sure that you're leveraging each one for the strengths that they have, whether that's the confluence. You get the pages um mixed with, like template repositories within github itself,.

B

Yeah- and you, like, you, said, use the tools you have, so don't uh don't gate. You know doing any of this because you lack say an internal chat tool or anything. You know work with what you have and get the message out and figure out how you can collaborate- and you know maybe improving the communication- is part of your mission or something.

B

Let's see uh next engineering blogs are a great way to uh get information out to the whole company.

B

If you look at our github blogs, we uh we post uh new things that are happening and and new uh new goals that the company has uh and doing similar things for inner source at your company is a great, is a great way to start so write a blog that explains what inner source is and what it means to your company and kind of talk about how you can get started.

B

You know invite people to uh your documentation, so they can look through how you're going to get started and uh teach users how they can uh get started, build building these repositories, opening them up teach them how to get help all sorts of things kind of pique their interests so they're looking for more information, so you can kind of build your core group of uh people that are trying to uh open up your uh projects at your company.

C

Yeah and definitely make sure that, like you, know the when you're creating these blog posts that you're continuing to like celebrate your wins so like when inner source works within a repository or within a specific project. Maybe you shipped faster or a new feature, was added because of lacrosse team collaboration, making sure to highlight that thanking the individuals or the teams, that kind of helped out across uh across, like your landscape, uh just making sure that people see that.

C

Not only did you know this, inner source initiative get kicked off, but it's also actually working, uh and it's also important to kind of share some of your losses. um It's okay to admit that, like something failed uh but identify like where you're learning from that. So you know when you first start with inner source. uh You know, maybe your cross team collaboration is kind of clunky.

C

uh Maybe your read and write permissions are completely skewed and messed up and, like you, you're having issues with that, um but making sure to kind of identify, like you know your missteps and then how you're kind of changing that and how you're going to make it easier, moving forward, uh a to make sure that the conversation's still happening about inner source uh but be you're just kind of also celebrating the work that's being done within the organization, which is always a good thing, because, as your organization scales, it becomes harder to find out.

C

You know what the different teams are working on uh and then suddenly you know something ships and they had no idea that you know something new was coming out.

B

Let's see so uh we'll talk about uh central communication channels, so here we're mostly talking about slack or teams or getter or any of those type of chat tools. If you have access to them and it's part of your cult, your company culture, to communicate over them, then utilize that highlight your successes. Talk about your failures uh and you don't need to do this solely in an inner source channel.

B

While that is probably a good place to do some of the communications, you want to kind of highlight these things across the organization so that you can get all the people at your company to realize how your source is helping you out, and that's also a great place to advertise your community of practice meetings.

B

So you'll have these meetings. You know every couple weeks or months, however, whatever makes sense for you you'll want to advertise these, so you can get more people engaged when you're having them.

B

And a very important one is standardize how you can get help at each with your projects. So if you have a ton of different projects inside your inner source, push it's very easy for new users to get lost. You want to kind of document a way for new projects and existing projects to help support their users.

B

So repository discussions is a great place to do that. That was a newish feature that github released a while ago. But if you want to have a chat channel for each project that works just as well just have a spot where users can go to get help, so they don't get stuck and they don't get lost.

B

A faq is an option, but you need to make sure you keep it maintained, and you also want to make sure that it's real questions. um Many of us have gone and looked at an faq with questions that you don't think anyone's ever asked. So if you do documentation that way, just make sure you update it.

C

Yeah and before we move on to the next topic, I just wanted to highlight uh one of the comments made by oleg, um so he identified that it's important part, like one important part of building a community, is finding champions uh in the target teams. uh That's kind of a talking point that we typically when we're interacting with customers about uh you know their inner source journey. That's definitely one of the things that we bring up.

C

um I kind of liken it to finding the people that would stand in line for a new phone um because they want to see like a new technology or see a new new way of working be successful. uh Another thing that you can do is start looking for teams that uh would provide some quick wins quote unquote. uh This is just something that, like you know, maybe their team is relatively successful um and it's maybe an application.

C

That's used internally by lots of different teams, uh kind of opening them up to the idea of inner source and having people, typically, their users uh kind of contribute, with either issues or bug, uh requests or issue bug or bugs or feature requests, as well as just kind of highlighting. You know ways that they can uh use the the rest of the company to kind of help build out. You know their specific application, so that was a really good point.

C

You know finding that internal champion on the team uh makes it a lot easier to make change, uh because if you are on a team and someone just told you that you you needed to change the way you worked, there'd be pushback. You'd, be you know, you'd drag your feet, um but if you had someone within your own team, that was saying like this is a really good idea. uh You know this is gonna, really revolutionize the way that we're getting things done. It's gonna make it quicker to ship.

C

That's that's, definitely a much easier path forward.

B

It looks like there's some questions about privacy as well, so I think from here we were going to start looking at demos, so this might be a good spot.

B

So if you look through here, I have internal repositories and private repositories and repositories with no uh no identifier. Next to them.

B

That means they're public, so internal in github in an organization means that anyone in the organization can see it so uh right now, just myself and one of my colleagues is part of this test organization, so they can see all of these, but they won't be able to see the uh private ones and everyone in the world could get access to this one right here and you can uh set that up in your somewhere in here.

C

Should be under, remember, remember, privileges, member.

B

Privileges, thank you uh yeah right here, and it looks like in this case my enterprise has said it so that my organization can't do this can't can't uh override it. So from.

A

B

Have to go to the enterprise and change it, but you can, you know, disallow public but allow everyone to create internal ones.

C

Yeah and then just to really touch on that uh the point so um the way that permissions work within github enterprise, either cloud or server, is that if an enterprise sets a specific rule, um then the organizations themselves won't be able to. uh You know override those specific rules. However, if the enterprise itself doesn't set the rule as say like a no policy, then the individual organizations can set those rules. So you know, if you needed to set it up said some orgs are able to create public repos, while others can't.

C

You would set that as a no policy at the enterprise level, uh and then you would have the organizations themselves maintain. You know what kind of repo creation um individuals would have uh as well. As you know, what the base permission of read, write, no permission, et cetera, so just depends on how you kind of want that to work out within your organizations.

B

All right are we good to uh go through the demos yeah? I think so all right. So uh this right here is a clone of the sap and resource portal. We have a blog that zach wrote a few weeks ago. I believe that kind of highlighted this as one of the options.

B

So this is super easy to set up. I cloned it and then set a new origin and pushed it to my test, org and then I set uh github pages up to uh to host it, since it's just a static website.

B

If you have another portal that you'd like to use that could work just as well. This was just easy for me to do so. I just put this one as public and if I drop that and check there, everyone can go look if they desire. uh So basically what this does is. It builds a inner source portal uh to view the repositories that are in this repose.json file.

B

So if we look quickly right now, we have two repositories in here. You can view them as a grid or as uh a table. It gives you links to them themselves and talks about how active they are, what language they're using helps you get to them.

B

So this is one way of displaying your projects. Now this itself is a static, uh repository or a static website, so it is just working on these reposed json file, so I set up an action which is poorly named to use uh this inner source crawler. So let me let me get that.

B

So this is a python script that uh zach wrote to generate the uh repost.json file.

B

uh You can go through the code here if you wish, but basically it will look through your organization for repositories that are tagged with inner source right here. So it looks like I've got three right now.

B

So if you look, um there should be a third one here. I think we may be having some actions issues but we'll add another one and see if we can get it to run.

B

So I will add miniature train. I think you are empty. Yes, I was doing some automation testing. I believe and that's why I've written my name a number of times there.

B

So if we go here on the right to the about gear and we type inner source as the topic and I'll show you how to configure what it's actually looking for here in a moment.

B

Then we go back to our action.

B

So here we've cloned the repository we've set up python within our ubuntu machine.

B

We install the requirements from the crawler, so I think there's only two yeah, the github uh repo or the github library in python and dot n, which allows us to use environment variables from a file.

B

We build the environment file and this is where we are specifying both the org and the topic that we're looking for, and I had to set a admin key for this one. But I believe that was so. I could check in files to this org or to this repo and from there we just run the uh the crawler and move the repo json file to the right spot and check it in.

B

So, if you look, this is a workflow dispatch uh this that, since this is just a test, one that works out great, but if you probably want this to be on a chrome schedule.

B

So if we go to actions and this we had some actions issues earlier today. So, let's see, if we can, we can get it to run without complaining.

B

They don't get picked up here in a moment.

C

Within, like a live demo to test the waters,.

B

Yeah, I haven't actually checked if we're back up so this could be interesting.

B

Hey we got picked up by runners, so all is good. So this takes probably only a few seconds uh 47 seconds, roughly.

B

So it should be done by the time we can get the logs even in here, so installing the dependencies.

B

There we go and we're done so. If I go back up here, uh the github actions bot just updated the repos.json file and we have miniature train right there at the top, and hopefully we still have the others in here.

B

Yeah inner source portal, etc, etc. So from there we just have to wait for pages to update. So this tells me that it's building, since it saw there, is an update to the repo it's rebuilding. This.

B

And it might be done.

B

So yeah, let's see there we go, and now we have all four from there.

D

So it's as simple.

B

As uh running that crawler and hosting this sap inner source portal- and you can get that get that set up all right- you ready to demo uh yours beard.

C

Yeah, absolutely um so, I'm gonna do a quick, quick screen shift sweet all right, um so I'm using something similar uh to the portal that uh chris was just showing off. uh This is another repository uh written by a github staff, member called enterprise showcase, uh and this specific repository builds out kind of this repository collection of all of the repositories within uh all of your enterprise.

C

So all of the organizations all of the repos can be displayed, uh but one of the things that I like about this is the use of this item called collections, where we can kind of create a uh list of repositories that we, you know are related to a specific form or function or whatever.

C

um So I have already forked this repository into a test org my test corp, which is doing really well obviously- and um the only thing I've done so far is I forked this repository over and then I needed to create a github action secret called like gh.

C

It's called someone accurate um yeah. I had to create a secret called gh ea token, uh and I just did that off screen. um So I'm gonna get this thing set up and start running uh live. So, let's fingers crossed on this one, um so this is a forked repo.

C

uh So the first thing I need to do is jump in and say like yeah, I'm okay with my ford repo running uh github actions, so I can click this and then I can jump into this generate repository list and, um first I need to double check and make sure that my there's that wonderful file- it's a good thing. This is written in my readme. That tells me exactly what I need to modify.

C

um I have this all memorized, uh oh right, in the action file itself. So if I jump into my workflow go into repo list, I just need to modify where it says: enterprise name here, um so I'm just going to go in here and click on this and I'm not mistaken. My enterprise is avocado or.

D

C

Yep, that's what I thought all right, so we'll just copy this over jump into this file that I'm editing.

B

And it needs to be that slug versus the uh friendly name.

C

uh Yes, I have this finished in another repo, so I can double check after I commit this, uh but yeah, let's jump in there for my in case things are broken. You can look at this thing.

C

Yep all right perfect, I know exactly what I'm doing everyone all right, so I'm gonna commit this real, quick and then uh right to maine didn't even create a pull request, so I'm living life dangerously uh and then I'm just gonna set this up to run on this workflow, and so this is gonna.

C

Do something similar to what chris's did, where it kind of created a list of all of the repositories um in the all of the organizations across my enterprise, um just as a heads up, avocado core is kind of like an internal or not internal, but a test, org enterprise that a lot of people at github use. So the repository list that gets created from this is very messy.

C

um There's a lot of just like oddly named repositories, with a lot of like random characters, uh because people are just testing different features and functions as they kind of go around their day. So while this is generating a repository list, I'm actually going to jump in and modify a file, because I want to create a new collection, uh and so this collection is actually going to identify repositories across different organizations within my enterprise uh and I've got a code. Space already fired up and ready to go to modify this.

C

So I'm just going to do some quick stuff here. So I'm just going to do I'm going to switch to a new branch here uh and we'll call this a new collection and then I just need to modify a file in my collections and this one's called cream. So we'll just modify this one since it already exists.

C

um So we'll just change the title here and we can call this. You know resource and then I can give it a better description and cheese rules. Everything around me so I can say, like collection of candy source.

C

And then I actually have my list of repositories in a window over here, so I can just drag and drop it in as opposed to you know watching me type, uh so I'm just gonna paste this in real, quick, just quick. It's just two. uh We've got.

D

That doesn't look right.

C

No yours is a dash here, right, yeah and then your. I forgot your uh your organization name.

B

What's your chocoratey's test org and the repo is inner source dash portal.

C

Oh, that's what happened there? I apparently like forgot to write things down. I actually need to do the same thing for my repo name, so we'll do enterprise showcase here.

C

And then you can say something like punches.

D

C

And then you get like super excited so for like a bunch of exclamation points. These are the best example repos.

C

uh So then, here I can jump in. Oh that's right, I don't have all right so we'll do hit, add, go, get submit here and, like you know, add new collection.

C

And then, uh if I jump in so here, I can get push yeah. It's going to tell me that I don't have an origin set up, so you know per usual, got to do the old connecting dots. I could also be doing this uh in the ui. All of this can be done over here on this branch thing, uh which makes it actually a little bit easier because it'll even do like your set up stream for you, uh but I apparently liked going hard way uh technically.

C

I could also create a pull request right from my code tab over here as well, but we'll jump in create a pull request, the old-fashioned way in the ui- and so this is just going to go back to main here as opposed to a contribution to the fork so say like add a new intersource collection.

C

You want. This, creates a collection.

D

For your source.

C

uh We'll create this pull request, I don't have any like branch protections or anything set up, so I'm just going to merge this blindly. um Just you know cross my fingers and hope that it works uh and then we'll just merge this in and see what happens.

C

So now, if I go to my actions, we're going to see that all of these things are going to start running, I'm going to let this run in the background, I'm going to jump back into our presentation, because I'm just noticing the time and then I'll come back and look at our website to see how this all looks uh once we've kind of gone through some more of the slides.

C

But hopefully that was helpful.

C

All right, um so, let's talk uh so now that people are maybe discovering your repositories. Let's talk about how you can make sure that not only do they find your repository, but then they can start actually using it uh and contributing to it. um So we're gonna kind of look at some of the different files uh and different things that you can do within your organization to kind of make these contributions happen.

C

um So the first and foremost is your readme, so your readme should kind of act as the welcome mat for your repository, it's the first thing that people are going to see outside of maybe like your laundry list of all the files that you have, uh depending on the size of your repo and some of the things that we like to make sure that readme's do is that they provide like a clear and concise message for what the repository is, what it does and then you know providing things like instructions on how to get started or even just linking to a getting started document um identifying where people can get help, whether that's an email, slack channels or team channels.

C

um Maybe you have a discussion within the repository itself, um but making sure that people kind of identify how to get started and then also how to contribute. uh Typically, I kind of recommend, if you are a new user or even a new employee on your team. What information would you need to get up and running on your repository and that's the kind of information that you need to be providing to contributors from outside of your team, uh and then we've also identified that you can also use code spaces?

C

I just use code spaces a second ago, um but we'll uh hopefully we'll have a little bit of time, and I can talk about some of the other things you can do with code spaces using uh dev environment uh settings so that everyone that uses your code space will automatically be set up for uh success and they don't have to set up like a bunch of stuff locally to get up and running before they even create their first branch.

C

um So some reading examples from across across the internet, uh we've got visual studio, code, adam and then github docs, all kind of have different takes on the readme. Both visual studio code and adam went super picture heavy. uh To get your attention, they've got.

C

You know, status, badges, letting you know that things are okay uh or maybe not okay, depending on uh the repository uh and then github docs kind of went for more like uh less less loud at the beginning, but it has a lot of information about things like how to start contributing uh and different things about.

C

You know how to get started, what things they are looking for, what things they're not looking for and that just makes it a lot easier for people to kind of find your repo and then get moving um outside of the readme file. We also have our contributing.md, so this is kind of the blueprint for how you want people to um make suggest changes to just uh you know, identify bugs, maybe actually submitting a pull request.

C

um If your repository is broken up into a lot of different repositories, maybe you're running like uh sub modules, um you can actually identify um how to contribute to those different files uh or how to contribute to those different repositories.

C

An example of that, for me is like the atom repository is actually made up of the atom project is actually made up of a bunch of different repos and they actually kind of create this image, and then they, you know, identify all the different areas within like the ui on like where that repository actually lives.

C

So you can actually contribute to the place that you want to make changes to, and so I've got some examples again of like how to contribute whether it's adam vs code or uh github docs, which doesn't look great on um but yeah white on white is difficult to read. So after we have our readme files and our contributing files are the contributing.md. Rather, we also have template files.

C

uh So if you aren't aware you can use both um issue templates and pull request templates to kind of guide your users on how to interact with either new features uh or bloodwork bug, identification or even just creating a pull request from the get-go. um So if we look at say the atom feature, uh yes, so this is a feature request on the atom repository.

C

One thing that I like about sharing this specific example is, within the actual feature, request template. They use uh comments to identify what they're looking for in specific sections. um But if you were to look at this as, like, you know, plain text or not plain text, but actually like formatted, it just looks like headings. You don't see any of these comments, so it keeps it really clean, uh but this just makes it so that if someone were to identify a new feature, they can identify.

C

You know a summary, their motivation uh and then you know whatever other information you are looking for. Whenever someone creates a feature or a bug report, if you use another system outside of github issues to manage your projects, you could always create an issue template that directly links over to that specific board or tool. um That way, if someone does create an issue within your repository, it's telling them like hey. We don't use issues here. We you know, maybe we use azure boards uh or other tools.

C

uh Please make that you know create an issue over here. Instead, um then, you also have pull request templates. um So the difference one difference between issue and pull request templates is that your repository can have multiple issue templates, so you can create different issue templates for different things, whether it's a feature a bug internally, we use issues for all kinds of things. So asking for time off, um you know maybe uh setting up like a new customer meeting like those are all issue templates that we have set up, so you can get pretty creative.

C

uh Maybe you want to create like meeting notes uh and you want to be able to just create an issue that identifies like you know the different areas of the meeting notes like attendees. What was discussed action items etc, um but with your pull request template basically, what happens here is that whenever someone creates a pull request within your repository, it's automatically going to kind of identify what information you're looking for. So, for example, you might ask for a specific issue that it's closing.

C

um You could also identify specific steps that you want the contributor to make prior to them. um You know submitting this, so maybe you want to make sure that they've tested tested this locally before they've.

C

You know put it on you to review slash test yourself, but those are two different ways that you can kind of guide your users um well, for if we can count all the files, um but there are a couple of different ways that we can kind of guide contributors from outside of our team uh to kind of alleviate that, like initial, I have no idea what I'm doing in this repo, but I like using this project- and I want to make it better um and kind of removing that makes it easier for people to contribute and they'll want to come back and continue contributing as long as they have like a good relationship with you know, whatever issue or pull requests they've created within the repository outside of the repository itself.

C

uh There are other ways that you can evangelize inner source uh within your organization and that can be done through things like hackathons. So you can have maybe a specific day of the week, maybe like open source fridays, but instead of open source you're working on internal projects, uh you could do maybe like an event during once a quarter or something where you just kind of identify.

C

Internal projects, you want people to begin working on, uh or maybe it's a project that doesn't exist, but it's like a an item that someone's always wanted to solve or fix, or maybe create something new for and kind of, creating a place for people to promote what projects they want to work on, and then people from across the organization can identify.

C

You know, hands up and say, like oh I'd, love to work on the docs for that or I'd actually like to help develop that feature, or you know, maybe looking at existing things, like maybe you've been intersourcing for three months or six months. You feel like your documentation's, a little stale or it needs to be updated. Those are all areas where we can kind of identify via the hackathon like these are the projects that need help feel free to raise your hand, and you know, make some contributions across the organization.

C

And then one thing that I like to kind of make clear when it comes to inner source within an organization or within an enterprise, is that when someone contributes to your repository from across your org, you should consider them a pain user as opposed to an annoyance or someone who's. Just uh trying to like bug you because they're giving you more work right.

C

um If you treat them like a paying customer, you are going to respond to them a little bit quicker, uh you're, going to read their issue or their pull request, as if it would change the how much money you could be generating with your project, uh and this just creates a better relationship between people that are coming to you and wanting to either create features or identifying bugs. um And then your response time. And there are ways that you can kind of identify.

C

What your typical response might be right, like maybe for inner source contributions or contributions from outside of your team. You're only going to look at those on wednesdays and fridays, but if you're clear about that and identify it in either the readme or your contributing guide, and just say that you know we look at crossteam collaboration on the following days. um You know, so you can expect kind of a turnaround time of like two or three days on any kind of pull, request or issue that you create if you're up front.

C

It just makes it easier so that people don't feel like they're being ignored, uh because if you create an issue and even like an open source project and no one responds to you, you're, probably not going to go back, I mean I'm sure. You've asked a question on some like web forum. No one responded, or someone gave you like some off-the-cuff answer that just didn't do anything.

C

You probably didn't go back or you didn't identify that that form or that community is like the solution to your problem moving forward, and you don't want that to be the case or the relationship that you start creating with the people in your organization, because you don't want to be the project that no one wants to help. um And then you know again going back to chris's uh topics on you know: either blog posts or chat channels, but making sure that you're identifying or advertising that your project needs help.

C

Whether that's going back to those blogs going back to those channels, maybe identifying it within your uh your repository topics. uh You know if we use something like chris's uh portal, we can identify that it's looking for you know, inner source needed inner source wanted uh help needed and it could automatically scrape those repositories and build out a collection of repos that need help.

C

And then yeah, so we kind of talked about. Oh well, I showed code spaces. I didn't really talk about it. I just kind of like showed you a cool feature and I was like yeah. This is a thing, um but code spaces is um essentially vs code with a full development um platform in in the cloud. It enables you to work on your repository um or someone else's repository with all of the different files and features within that specific repo, similar to what I had going in my uh vs or in my code space here.

C

But one thing that I didn't show off in this specific code space is that we can actually set up um a dev container file uh in the repository itself, um so this devcontainer.json file actually defines what your dev environment is going to be for a specific code space. So whenever someone creates a code space within your specific repository, they'll actually be able to work exactly how you need them to work, or you know, with whatever tools.

C

They'll need to be successful without have them having to do that locally, and this is going to help um increase, intersource contributions or cross team contributions, because they don't have to get set up. It's not going to take them. 30, 40 minutes just to get up and running before they can create that first branch, or that first commit they can actually just hit the vs or the code. Spaces button open up code spaces and get right to work, create their branch start.

C

Making changes create a pull request right from the web and uh as a slide set. um It's going to be g8 this summer and you can sign up for beta down at the bottom.

C

And then now we're going to wrap it up.

C

So, chris, you have anything that you want to mention on any of the stuff that I kind of blew through.

B

I'm really excited about code spaces and how that can help open source and intersource alike. Helping people like you said, get those dependencies installed quickly without having to fight with getting your uh getting your environment set up. That's really gonna, I think change things.

C

Oh yeah, I mean absolutely, I mean you could jump into a code space here um so I'll just create one really quickly off of this specific repository.

C

And so, while that's doing that, why don't I check on my action all right, so we should have a website here.

C

That's fun! That's what I'd like to see perfect.

C

uh Let's see if this is wrong yeah it did.

B

Do we screw up the json somehow.

C

D

B

We didn't even edit the json did. We that was generated yeah.

C

I mean we've got repos yeah from all the, although all over the place. Well, this is fun. Nothing like failing failing live on a friday. This is a good start to the weekend. um It's what I like to see. Well all right, so I had I had a contingency for this as we as we saw. um So I have this repository. That's finished so I'll jump into this code.

C

uh It's not loading.

C

huh No bueno, that's not fun. Well,.

B

Ours are great.

C

Yeah, so it would look like this would be a long laundry list of all of the repositories that we have, because we have thousands in this thing and then the collection would have the different repositories with their topics. uh Trust me: it works on my machine.

D

C

If I jump back into um this specific thing, so let's see, if I can't do an npm start and then open this up in my browser, and so I have no idea what I'm doing with this specific project uh that I forked um I was able to create a code space for it um in the instructions it says to run. Npm start, and now I have a working app all in what you know: 30 40 seconds, as opposed to like having to bring this down locally, clone it and everything else. So yeah, it's very cool.

C

I like it a lot, I'm looking forward to it being uh available broadly and people to be able to work in it all right, um so yeah, just wrapping up um discovering repos is hard, so make it a little bit easier, whether it's through either of the portals that uh chris or I pretended to share um or find other methods.

C

You know uh you know the two solutions that we provided aren't necessarily the only answers but making sure that making uh you know whether it's user, permissions, uh showcases um or even just having some form of like you know, list of repositories that people can help out. On, um or you know should be collaborating on is definitely a good start for your inner source journey.

C

um Some technology that can help are, you know some of the features that we covered on github itself, so specific files, uh user permissions within the orgs organization or the enterprise, as well as things like code spaces, uh things that we didn't touch on are things like. You know, projects, uh github discussion or repository discussions um and then any other tech that you can think of. That could help with inner source.

B

It's really, in my opinion, a cultural change like you can you can get in your.

C

A

Without any of this,.

B

Stuff, you just have to really want to and and help help your organization get into it. So all this stuff is very helpful, but you, uh you really gotta talk to your your teammates at your uh businesses and your organizations and learn how to share your code and it's a very hard first step.

C

Yep absolutely and then uh finally, just building a culture of sharing um yeah. The biggest thing is, you know, being comfortable um being comfortable sharing your code, a lot of people that we talk to about inner source, they they kind of hem and haw, and they have this idea of like well. The repository is not ready. The code's not ready to be shared yet um nobody's code is perfect. It's okay! If your code's a little messy your, maybe your code comments are terrible. uh Maybe you don't do code comments.

C

Maybe um you know you've got a lot of open issues that you still need to deal with. um It's all right. Other teams, within your organization most likely have the exact same problems. They're, not going to think it's odd that you know you have four pull requests and all of the tests are failing. um So it's all right. You know like share it, get your repository out!

C

There make it so other people can consume it and use it, and then you know make it easier for them to get their project shipped, because you know maybe they're not contributing to you but they're consuming it and that's making it a lot easier for them to ship quicker as well, which is also a win for your your team as well, and then, as chris mentioned technology, isn't necessarily the only thing that you need for inner source to work.

C

Actually it isn't it's definitely a cultural thing, but utilizing the technology that you have uh thoughtfully um to get this thing up and running is definitely a major key to success.

C

And then again, uh just a quick reminder that if you would like to uh book a demo with anyone from our professional services or field services, teams feel free to just take a quick pic of that qr code and uh it'll get you all set up for success. Who knows? Maybe you'll get a meeting with either chris or myself. uh You'll probably want chris, because he had his things together today and my demo was was a hot mess um or maybe you'll get me and I'll I'll be a little bit better. On that specific day,.

B

It's how things go when you're trying to do it live.

C

Oh absolutely I like knew. I woke up this morning like it's, not gonna work and it's gonna feel real good. Let's see if this is a yeah hard pass.

B

C

B

That uh actions outage a little while ago, I was prepping the demo and I was panicking. Oh boy, it's going to go badly.

C

Hey listen at least I have a description and topics right.

D

I'm ready right, yeah.

C

Half the battle.

B

um I do see some questions in here about uh point and click for uh pipelines and readmes, so uh somewhere in here, beard did show that you can edit all this stuff uh live or you can edit all this stuff through the browser.

B

So if you have edit or push uh permission on repos, when you click on a file, there's a pencil icon that you can click on and make your commits through the ui.

B

uh So assuming that's what we're talking about, uh you can definitely do that and it does make updating documentation very quickly. Often.

C

C

Okay, I I wonder, if that's more, that might be more specific to creating github actions so kind of like a like a drag and drop slash like drop down list. Okay,.

B

We do have the workflow templates, but that's not really the same yeah.

C

I know that actions is constantly being modified. Enhanced. um I wouldn't be surprised, and you know I'm I wouldn't be surprised if features like that are potentially done. um I have no idea if that's um going to happen, but I I can see that being like a next evolution of of actions to make it. You know, make it easier for people to get started with. You know, like you know your first pipeline kind of adventure right, so that would be very cool, make it a lot easier for people to get started.

C

um I know that we have workflow files and templates, and that definitely helps, um and then I I do find that when I use actions that I'm I'm drawn to the actions uh on our marketplace that have like a well-done readme with a good example uh of how to get this thing up and running um so that I can get started with an action as opposed to like trying to figure out how exactly I'm gonna use this thing, but visually it'd be really nice too. I agree.

C

All right and then um was there anything else that we saw that looked really awesome.

B

um We did, I think we put it in chat, but we have a repository with all of these links that we'll share out, uh so that should get you to uh the documentation here, as well as these open source, uh these open source portals that we were showing.

B

B

uh Let's see, I think that might be it beard.

C

Sweet well, I hope everyone has a wonderful wrestle. You know rest of your day or maybe it's already evening, so I hope you have a good start for your weekend, thanks for including us in your weekend, plans um so yeah. I hope you have a great day and I hope you have a great weekend as well.

D

D

D