 All right, recording has started folks. Welcome. This is just a little bit of a github workshop for the open organization ambassadors at opensource.com Thanks for joining Going to just walk through a couple of basics regarding github We moved here as you know our community moved here recently as a sort of a public home base So we could work more transparently work more in the open And that's what we're going to do and I have just a couple of notes here on some github basics that we can review because some of the Ambassadors expressed an interest in learning a little bit more about our home. So I've got some notes over here I'm going to go through And we'll just cover the basics But the first thing that I want to say is that github really is a public Issue tracker at heart and that's why we're using it. So Chad Whitaker One of the open organization ambassadors just wrote an article about this that we'll be publishing in a couple weeks But the notion here is that using a public issue tracker allows People to see what you're doing how you're doing it and why you're doing it in public every step of the way and so Using github as an issue tracker allows us to keep our work out there allows us to keep us to keep us accountable for the work that we're doing and it allows us to Have a common point of reference when we're talking to each other and talking to newcomers that we can link to and show Them what we're doing in public with no walls So we use github for that tool and so when you go to github at github.com You'll see the opening screen here. You'll need an account to participate So at the top of the screen you can either sign in or sign up. I have an account. So I will go ahead and sign in When you sign in you see a couple of things right on the landing page of github Github functions as sort of a social network for coders. So you've got some Social elements to github some things that keep you connected to your network the people who you're following or the people who you're watching The people with whom you're connected online So on the left hand side, you will see a bunch of folks a bunch of activity from folks that I follow So, you know, this is one of our ambassadors here in is doing some stuff and You can see his profile here Which demonstrates, you know, sort of one of the social Elements of github that you can follow folks who are doing activity and do doing activities and doing work contributing to different projects So I follow here in and I see some of his activities. It looks like he's starred some repositories. He's made some contributions We can also see down here that ambassador robin mulwick who's on the call today is also doing some stuff And he has commented on an issue related to some open organization ambassador work So you just get an overview of what's been going on in your network, which is kind of nice On the right, you see a list of all the repositories that you contribute to and we'll talk about repositories in a minute And you also see a listing of the things that you sort of own that you have ownership of so that's just what you see when you First log in so the what we're going to do first is talk about some basic terminology and basic nomenclature On github sort of the the primary unit of functionality on github is what's called a repository and it might be a little bit of a gross generalization to say a repository is like a folder but In essence, that's what we're dealing with so let's go ahead and visit the open organization ambassadors page On github, which is github.com slash open dash organization dot dash ambassadors when you go there You'll see a couple things the title of the repo title or a title of the repos I should say here the people who are contributing to our little group on github and Then a list of these things called repositories and really our repository is a place where you keep all the files and the Work related to a specific project that you're doing so One of the things that the ambassadors have been working on lately for example is the open organization definition And these are listed here in the order in which they've been most recently updated So seven days ago somebody made some changes to the open organization definition And so that is the most recently updated repository and it's at the top So a repository again is a place where you store your files that are related to different projects Since this is a major project for the ambassadors. We created it our own repository for it So inside this repository when you click on it You'll see several things the first and foremost what you'll see is a list of all the files that are related to this project And what github does it when you create a repository is it automatically looks for a file called readme and That then what it does is it reproduces that readme file down below? And so it's important as one of our writers said just this past week on the open organization section of open source comm to have a very Concise an explanatory readme file so that people who are coming to your repository Can understand what your project is about and what you're trying to do and that's what this File does it explains what the project is so this explains a little bit about what we're doing It shows the current version of the open organization definition when it was last updated and things of that nature Inside a repository not only do you see a list of files, but you can see a list of other things as well We'll start here at the top The first thing and one of the most important things for the work of the ambassadors is going to be this tab up here at The top called issues when you click on issues what you'll see is A list of sort of tickets or discussion items and you can think of issues as kind of a meta Commentary about the files right so it's not the files themselves But it's sort of our discussion about them and what issues are is there this is what? Chad loves and you'll read in his article is that this is where we can keep track publicly of all the things we Note about the files are all our to-do items related to the files or all our questions or concerns or proposals regarding the files So for example, you'll see here that for the last couple of days We've been having a discussion about expanding the definition to include some kind of maturity model And this has been a discussion that the ambassadors have been having in earnest over the last couple days So when you click that what you see is An entire conversation related to this particular issue and people have been you know sounding off and giving advice and chiming in with their opinions and it just flows like a regular discussion and So what this is is it's an issue or a topic related to the code that's in this repository And there are other issues as well. So for example somebody thinks for example that we should Recruit an amp a new ambassador somebody who's familiar with the work going on in the so-called sharing economy So they put this item here so that it's now public and it's now something we can track together So the important thing to remember about issues is that they can become a sort of Vocal point for the work that you're doing a place where discussion happens about the code that you're doing in your repository So let's take a look at an issue. Let's go back to this issue about expanding the definition with a maturity model and You can see here that people are Responding to my initial post about this idea Chad did several things he Posted a comment that said I love this progress and he also Put a thing here a little emoji because Chad loves his emojis you can respond to the post with emojis by clicking this button here and You know leaving your feedback You also see a couple other things that you can do with an issue You can subscribe and unsubscribe from it. So that means when you When somebody makes an update to the issue what they leave a comment or post a new file or something like that you will receive an email about The update to the issue and the nice thing about github is that when you reply to that email? If you reply to that email from your email client it automatically adds your reply to the list of Conversation items that are going on down here So you don't even need to necessarily log in to github to leave the comment or to leave your response You can simply reply to the email and it will add it right here to the conversation Which is a nice time-saving feature for people who spend a lot of time in email Where was that a follow feature or where did you click to? If you to follow the repository or to follow a user Well this this discussion if I wanted to follow this discussion, right? So if you want to follow the discussion, there's a button now I'm subscribed so that it would want me to unsubscribe at this button down here. You can click Under notifications and that'll help you follow the discussion You can also do several things To the repository itself and I'll get to that in a second where you can actually follow all activity going on in Repository this just subscribes you to the issue itself So if you want to know about this thing, but not all the other conversations that are going on about this repo Which is short for repository you can do that here You also see a link or a list of all the people who have contributed so far to this conversation right below that button So you can quickly see at a glance who's participating in this discussion and several of the open organization Ambassadors have already contributed to this discussion Now this is the thing that I think most of the ambassadors will use most frequently So I think it bears lingering on this for just a little bit to show you a couple of features that make Interacting with one another one another really easy So for example You can see here that people have been at mentioning one another so we'll start with that as his common parlance for example on Twitter You can see that People are using at replies as I did when I mentioned Robin up here And as I did when I mentioned Sam down here to call other people out in the repository Folks who are members of the group and folks who are already contributing to the conversation and be referenced via An app mention so for example, I can type Great idea, and I'll mention Robin because I know he's on the call today. I can put at and see it automatically Populates with some of the folks who are participating in the discussion and some folks who are part of the open organization ambassadors group So I want to reference Robin. So I'll say great idea Robin Hit that and it will automatically put Robin's name in there In that way when I commit or this comment when I send it to the group Robin will get a notification saying hey Somebody said your name and once your attention on this issue simple, but it's nice way to get folks To pay attention to what you're saying and to notify them that they are that they're being talked about or that they're being asked The question so that they don't have to constantly check this so that they might not miss Something that's being said Now the other thing to know about Issues and about github in general is that it's markdown friendly and markdown is simply a Markup language why the name is kind of funny and ironic It's a markup language for plain text and allows you to format your comments in your text Really easily using common keyboard characters. So you can do several things. So I can use a hash sign to make a headline for an idea and I can also use asterisks to make bullet items I can do things like Make Words emphasized by using underscores on either side of them and I can also Make them bold simply by putting two asterisks on either side of the word And those what those things allow you to do is do basic formatting without having to fiddle around with things up here Or what have you now? I'll just click hit preview to see what my comment looks like and you can see that By including that hash that hash I was able to make this headline by including those asterisks I was able to make this bulleted list by including those things I was able to do this And so that just helps you make comments more quickly and without having to fiddle around with a lot of Formatting and things like that but the one thing that is really important and really interesting is referencing other resources So not only can you reference people you can also reference things that are going on in the repository itself So as you saw there when I hit the hashtag It brought up a list of issues that are going on in the repository So let's say that we're having a conversation and I want to reference another issue that somebody else has raised You know maybe Robin. I say Robin. That's a great idea You should see our conversation going on over here because we're also talking about that I can hit the pound sign and it will show me a list of issues that are going on inside this repository so Let's say I want to reference this issue about recruiting an ambassador from the account from the sharing economy universe I can say hey check out issue number five. We're talking about that and if I just put number five When I send this comment You'll see that the hyperlink has automatically been created and it automatically when you click it goes to that issue So simply by saying hey check out number five check out number six whatever You can send people to other issues and build on the conversation pointing people to other work to find the number of the issue By the way, you can find it up here in the title and you can also find it up here in the URL It's always the last number in the URL So that's a nice feature that this sort of markdown enhanced environment gives us what we can also do is we can Link to things outside the repository or anywhere on the web and that's very easy as well Let's say I wanted to link to hearing's biography Or his homepage here his bio on a github I'll say to Robin you should contact Hearing and now let's say to make it easy for Robin. I want to link to hearing's page. Well in markdown. That's really simple I can do this open bracket character and this closed bracket character on his name to show him that to show that I want this thing to be clickable and then you have to tell github Okay, where do I want the person to go when they click hearing's name? I'll go over here grab the URL from this window Copy it put a parentheses here put that URL in there close the parentheses and now when I preview this I'll see that when I send this comment if I click on hearing's name or if anybody clicks on hearing's name It will go right to his profile on github and you can do that with any web page on the on the worldwide web So we use this for example a lot of times when we are sending people outside github to look at different things I did it here for instance when I was talking to Lara and I wanted to reference another issue in another repository. I made that a hyperlink there and The last important thing to note and something you'll see people doing already in the thread like Robin And I and Lara to some extent is quoting and citing one another and that's also really simple to do So let's say that I want to respond directly to Robin's comment And I see the part of his comment that I specifically want to respond to is this one right here So I'll copy that When I make my response And I'll say great idea Robin you said and I'll go down here And I will paste that part of his conversation in here because that's what I want to respond to It's easy to quote that in my response simply by putting a character right in front. I do that put that character there and Now you'll see when I send that comment That it's cited Robin made it a little bit grayer to show that I'm quoting him at length And then I'm responding to this particular part of his comment and Robin you can see and this repository already did That for something that I said so his is a good example Of that So that's just a little bit of sort of markdown basics But it's a great way to interact with folks in comments and your fellow ambassadors Inside of github it makes responding and collaborating a lot easier when you know sort of some of those shortcuts especially the shortcuts for At mentioning one another mentioning issues like that And hyperlinking with this character and these characters. So Anybody in the call on the call or at the meeting have any questions about this part of the of github using issues or working with markdown Pardon my Reach here while I Look at the notes So as I said before I think that's really where most ambassadors are going to spend their time is hanging out in In issues talking to one another Well, let's say you wanted to do more than that. Let's say you wanted to contribute to project to a project Let's go back here to again the open organization definition This is the home page for this repository and you can see up here that you can do several things So Jeff in response to your earlier question about how you can follow things that I showed you how you could follow an issue But this actually show shows you also how you can sort of follow an entire repository You can do that up here by clicking watch or unwatch when you're watching a repository You are getting updates about that repository on your Home page in that list, but you're also getting emails when people do things like leave comments on it or make updates to the files That are in it So this is really handy for getting notified when people are doing work on a project that you really care about or that you're invested in So you can click that to watch the repository and that will send you updates when things happen to it You can also star the repository and starring a repository is really just like bookmarking it It allows you to make a note of it. You don't get updates about it. You don't receive any Additional notifications, but it allows you to kind of keep a little private set of bookmarks on your github account Of projects that interest you that you might want to go back to you You'll see that our buddy here here and is sort of the king of starring projects He's starred 672 projects on github things that he's interested in that he might want to come back to later And So those are some things you can do up here and the other thing you can do is fork the repository Now in open source terms a fork is a copy And it's sort of also in github language You might hear some people refer to making a clone of a repository cloning it when you fork a repository You are essentially making a copy of that repository which is owned by someone else on your own personal account When you click the fork button, it will take this entire Repository all the files that are associated with it and make a copy on your account so you can make changes to it and Mess around with it play with the code play with the wording and not worry about making any permanent changes to the Master copy the one that's sort of the owned by the entire group and I'll show you that I've done that with the Open organization Definition we'll go to my profile here and you can see a bunch of repositories that I've made I go to my repository listing and Here's a copy of the open organization definition repository that I've made because I wanted to update it and make changes to it But I didn't want those changes to automatically override everything that the group has already done So I made a fork of it And when you click this button It does this neat little animation of the github making a photocopy and putting those files on your own account So you can see if you look up here in the top left corner that this is me I'm semiotic robotic on github and pretty much anywhere else And then I've got a new repository in my account called open or definition Which is an exact copy of what you saw in the ambassadors group and Now what I can do is I can use my favorite tool to Mess with these files to make copies of them to change them and there are a lot of different ways to do this We won't cover that in this tutorial, but you can see open source calm specifically Seth Kenlon series on using github to and get it spent especially for Getting some different tools you can use to Mess around with github files But one nice thing about working on a lot of projects with the ambassadors and much of what we do is text and not code And so you can actually work with text right in github itself You don't need to do a lot of other work or use special tools So now I have this copy of the open organization definition in my repository My own repository, so I'm going to click it and I'm going to pull up a copy of the file Now this is of course one of the ambassadors largest projects to date Which is making a definition a working definition of open organization? And you can see that we've outlined the language here. We've got a nice long text file Because it's basically text. I can use The github editor to make changes to this file and I can do that up here in the top right corner by clicking the pencil icon now what it'll do is it'll bring up an editor and Now instead of it rendered in publishable sort of HTML It's again bringing the file here in markdown Which is again that markup language I told you about that you can use in plain text mode to make changes to files And so here is the open organization Organization definition lined up entirely as a markdown document and I can go through here and I can make changes You know I can change the version number. I can change the language. I can play with this file And you can see I'm using similar conventions as the ones that I use in comments one pound sign for a first order headline two pound signs for a second order headline and when it all When it all comes together when it looks formatted it will look very nice in github like this So let's say I wanted to make a change Say what I wanted to do is I don't like the word characteristics. So I'm gonna say I Think we should call these qualities of an open organization not characteristics So I'm gonna go ahead and say I think that is what I'd like to do and I might go through and do some other work The next thing I have to do is I have to Commit that change right so github works with what's called version control And it keeps versions of files and a history of those versions so that at any point Anybody can see a history of the project that you're doing that history of the project that you're working on and It allows you to revert back to a previous version if you don't like the changes that somebody made or you decide that a Previous version was actually better more functional or in our case sounded better But what I'm gonna do is I'm gonna say well I think that should be the word qualities and that's a change I really want the community to look at and consider adopting for this for this project So I'll go here and I need to make a commit. I need to commit this change to the project You can see down here that github has already Pre-populated these fields with some things that it recommends I put so it says, you know I should call this commit or name this commit update open org definition. I think that's fine I'll keep that but what I can do here is add a small description for What this commit can contain so that when people look at it when they see that I'm making changes They can see at a glance what I'm doing and why I'm doing it. So I I'll type here I recommend That we change the language In this line And now what I can do is I can commit those changes so it's gonna take the change that I made Attach that comment to it and now you'll see My copy here It has made that change And that says qualities can you talk about the difference between committing to master and creating a new branch I can yep so That functionality is often Most useful when you're working directly with the group's project so I created my own copy of The document before I started working on it and so Jason is asking down here at the bottom about creating a new branch or Committing directly to the master branch and you have the option of doing either of these things when you commit directly to the master branch What you're doing is you are making changes to the master file In this case I'm the only one with access to this because I made a copy of it and put it in my repo But let's say I was doing this in the open organization ambassadors repo Then I was making changes right to the document that everybody else had access to and so in Organizational terms this is sort of kind of not sort of a coding faux pas and Not necessarily a best practice community wise because you're making changes to a master document without asking anybody what they think And just kind of moving ahead When you create a new branch what you're doing is you are actually saying okay, I made these changes to this file Push them back up to so people can see them But don't overwrite the original make a separate copy that people can look at first before we do that Now because this repo is mine and nobody else is working on it I just pushed to master because it doesn't affect anybody else So I've made this change and I'm going through my individual copy of the document I'm working on it here and I say okay, you know I really think that I should notify the other ambassadors that I made changes to this document And that I want them to adopt those changes in the master file What I can do is I can go do Open organization definition and it shows here That I have made a change what that's called a commit That puts me out of sync with the master repository the master project that the open organization ambassadors are working on So what I'll need to do is I'll need to request that they incorporate my changes And that's how that's another primary function of github is what's called a pull request I would like the open organization Open organization ambassadors to pull my changes into their master document I can't do that automatically from here, and I shouldn't want to because day quorum indicates that I should ask their opinion first about whether what they think of my changes But I will request that they take a look and consider pulling my project into theirs So what I want to do is I want to go right down here to new pull request and click that button And when I do that it brings up this screen, which it says it's comparing the changes So it shows me what is currently in the ambassadors repo on the left and it shows my modifications on the right And What it's doing is it's saying you are requesting that the master document be changed so that what's on the right Becomes the master document and instead of what's on the left So what I can do is I can Hit commit pull request I can as you can see it updated with my Updated here with the title of my pull request and the description that I already wrote tells folks in the repository what I'm trying to do And then I hit create pull request okay And github has already checked it out said that the changes I want to make aren't going to override what anybody else is doing And now we're back in the open organization ambassadors repository And we can see that when we go into the open organization definition the master document the one that all the ambassadors are working on We can see that if we go to pull requests up here at the top We can see there's one outstanding issue And lo and behold it's mine. So other ambassadors can look at this now by clicking on it And they'll see my comment and my title and what i'm trying to do And they can see line by line the commit i'm trying to make and the changes i'm trying to Have accepted They look just like this and so what uh ambassadors can do is say is look at these look at them line by line And say okay, I like what's going on here. I don't like what's going on And then of course as is the case with all other Things you can do on github you can have a conversation Which is where these things usually go and the conversation is the master view here. So people can read my requests. They can look at my proposed changes And they can start to leave comments here On this pull request and we can have a discussion and this is normally how things work on github You know somebody proposes a change it or I request that they pull changes into the project and then people have a discussion about it Well, I think this is valuable. Well, I don't think this is valuable This is where that conversation happens Not every pull request gets accepted and some pull requests ultimately get rejected after a good deal of discussion But what you're doing here is you're saying I have done some work I'd like you to review my work and if you like my work I'd like you to pull those changes into the master document And so that's how a pull request works and that's how You know the ambassadors can collaborate on some of the work that they're doing right here From github. So that's another important part of Using github to do our work Those are really in terms of github basics the things that I would say are the most important features that ambassadors need to know about A couple other things that you can see here from our new home on github right from the home page Is that we have a list of the members of the organization? So here are the open organization open organization ambassadors who are on github the open organization ambassadors By virtue of being an ambassador one of the perks of the program is that you get to have push access to the repository So you have that power to go into A document like I just did and make a change to it A github user who's not a member of the organization can't just come in and click that pencil and start making changes as I did But github open organization ambassadors on github can do that Another thing to note here is that as it is sort of like a little social network You can click on the people tab and see everybody that you're connected to On github see what they're doing see what they're up to leave them private messages Send them notes send them links and things like that. So this is a place that we can use to Collaborate a little bit more and to communicate if you want to use this over email for certain tasks Sometimes it streamlines people's work if they can use this Instead of email for leaving notes and leaving messages And then another thing you can do is again because you are ambassadors you can actually create your own repositories and You'll see that I created a new one most recently that I called the ambassador boardroom And so I want to point this out as we wrap up here just as a sort of a point of order This will consider our sort of meta repo. It's our it's our repo about our github presence on For the open organization ambassadors so What you can see here is when you go into the boardroom we have several issues that are raised and It was Chad's recommendation and I thought a good one that The ambassadors have a place where they can talk about at a meta level the The organization itself and the repo itself So for example here, we've posted up the project agenda for 2017 This is really a comment about the work that we're doing and so it went in the boardroom I put it here and people have been discussing it and taking a look at it Of course, I hyperlinked it so you can click that and see a copy of it And that's part of the boardroom So what the boardroom is for is for discussions about things like hey, let's have a github tutorial for the ambassadors To teach them how to do some of the basic github functions. Well, here it is and we plan this very Seminar today on github. Here's a copy of the A copy of the outline that we put that Chad and I put together for this very project And there's other things on here, you know Chad is leaving notes about his intentions to write articles And things of that nature so the boardroom is a place where we can talk about our work Where we can talk about our projects and where we can leave sort of The work of planning what we're doing And so that's what the open organization ambassadors boardroom is really for that's that that's that repository Other repositories that we have so far not in addition to our working definition of the open organization include A description of the ambassadors program itself We keep that in the repositories that anytime people can propose changes to the description of the ambassadors program itself And the community produce guides to the open organization by Jim Whitehurst We have the leaders manual catalyst and chief and the open organization field guide all those projects Of course are public and their source code is hosted by the open organization ambassadors and we Manage the version control on those So that's a little bit about our new home on github some of the basic functions and how github works and what we can use it for We have about five minutes remaining anybody have any questions I think I covered everything on my notes All right, great. Well, we're going to make this video public and we are going to share it so that any Incoming ambassadors can look at it and anybody who's currently working can get a better sense of our new home Welcome to github everybody. Thanks for your participation and we will see you soon. Thanks Brian. That was great. Thank you