 Hi, everyone. My name is Luke McGinnis. I'm one of the co-organisers of the conference and as part of it this afternoon I'm going to be giving a very quick introduction to GitHub as a platform for storing, accessing, and sharing or code. And so do feel free to tweet at me. I am recording this session asynchronously just because we can't have more than one live stream on the YouTube channel at the same time. And so I will be available to answer questions. So just either in the Slack or on Twitter. Just let me know. Just to start us off, a quick public service announcement. Being Irish, I print the letter after Q a bit oddly. So when I say or, what I really mean is are and most people working with this computing language sound like a bunch of pirates to me and just in case I slip into it over the course of the presentation, you've been warned. So just to give you a brief overview about what I'm hoping to cover through this and it's going to be quite interactive and that I'll be working with GitHub itself. And because of that, it may not be completely smooth. I may run into some issues, but hopefully fingers crossed everything goes well. And so I've broken it down into three kind of sections, each getting more involved in your interaction with GitHub as a platform. So the first is if you're acting as a consumer of code. So looking at how you can install or packages from GitHub and what a lot of the information on GitHub repository is actually mean and how you can make lists of packages you think are interesting or follow creators or other coders that you think are producing interesting things. So you'll be notified when they release something new. The next level up from that to my mind is a contributor. So if you actually want to create your own repository on GitHub, if you want to let other creators know that some of their code isn't working as expected, or if you actually want to contribute to your own code to another project. And then we're very briefly touch on copying a project from GitHub into or studio locally. And at the final level, and we might not get to it today, but if not, that's fine. The advantages of GitHub for hosting or packages. So this is aimed at those who already have or packages, but may not have them online on GitHub and maybe hosting them locally. And it's just trying to work through what the advantages of using GitHub as a platform are in terms of book tracking using things like automated testing or continuous integration and then building a package website. So we're starting from the ground up. I'm working our way through. So hopefully we'll touch on something for everyone. So just to note, what will not cover and is setting up get to work with or studio. And because this can be quite finicky to help set up remotely, particularly since I'm not doing it synchronously anymore. It's just an extra level of difficulty. I'm not going to deal with the day, but there are two key resources. I'm going to point you towards if you want to set up get and as part of this workshop. So the first one is happy gears and GitHub for the user and that should be a capital or event plan words, but it's brilliant. It's happy gift with or and it's an online free book. There's loads of resources there to help get you up and running really quickly and highly recommend it. And then the second one is dang it, which is fixes for common mistakes made when using it. Yeah. So the first thing I want to talk about is just very briefly the distinction between gift and GitHub. So it is a software on version control software, which allows you to organize and maintain different versions of the same file. So you can track changes to files and to projects more generally over time. And GitHub is an online cloud based platform that allows you to host get based repositories. So it's an important distinction. They're not one of the same. And so get is a software and GitHub is the platform. But GitHub offers a lot of functionality beyond just hosting these GitHub like these get excuse me repositories in terms of issue tracking in terms of package websites, things like this. So we're going to explore some of that as well today. But just to note that going into this gift and GitHub are not the same thing. So I'm going to use one of my own packages as the example. So we're just head straight to GitHub.com to show you. I'm assuming for this, I'm just going to hide the controls here. Just give me one second. So for this workshop, I'm going to assume that you've already set up a GitHub account. I know in the Slack, I encourage you to do so. If not, it doesn't matter. It's something you can do later on. But for me, I'm assuming that when you go to GitHub.com, you're getting this homepage view rather than please sign up for you. So I'm going to use one of my own repositories as the exemplar. Well, exemplar example, I think it's better exemplar might be a stretch just to show you and talk you through some of the common aspects of an all package hosted on GitHub. And so when you go to an all package, your first view is of the files in it, which are up to top. You have some extra information on the right hand side. Often there's a short description and an about section, which tells you a little bit about the package, what its purpose is, and then maybe link to a website. Often this is where you can find more documentation. And you also have common tags. So these are useful if you're searching for a particular package using the search bar up here. You can use these tags to try and find related packages. And you have the contributors on the right hand side as well, which show you the people who've contributed or made or created code for this specific package. So here you can see that myself and a few other people have written code for this package. Rob this. And but then arguably most importantly for people at the consumer level, so those who just want to use code from GitHub is this section of what's called the read me, which is an introductory piece of text providing again some context on the package. And most importantly, some information on how to install the package from GitHub. Now, most of you, even if you haven't used GitHub, the platform before, it's likely that you will have installed packages from GitHub. And there's a range of reasons why you might do this. The most important is that the package version on GitHub is often where a lot of the new developmental functions are released first. So you might, the version of a particular package on GitHub might be more advanced than that, which is available via crown and via the common install packages command. So you can see here that, and again, this is an important part of GitHub repositories, the read me badges. And not all repositories will have this, but if they're there, they're often very useful. So you can see that I've been a bit lax in the last while, and the last version of this package that was uploaded to crown was over a year ago. Now I've done a lot of development work on this package since then, but it's only on the GitHub repository. So that shows you there's some advantages to installing packages from GitHub. On the flip side of that, installing packages from GitHub, they can be less stable because they are developmental. So oftentimes installing from cram is the best way to go, unless there's a specific functionality you know is available in the GitHub version of a package, but not in the crown version. So there's two other things I want to point out here quickly, just so you can get an idea if you stumble across a package on cram, you get some sense of how good or the level of quality of the package. And these are the RCMD check and is passing. So what this is, it's an indication of whether you'll be able to install the package properly, pretty much. It shows that it's passing a lot of the common tests that all packages have to go through. So if this is failing, it often means that the developer is actively working on the package and it might not be robust or you might want to wait a little while until they're finished working on it. And then the other thing is this thing called code coverage or code cup. And again, a higher code coverage just means the developer of that package has spent a bit of time writing tests and showing everything works as it should. And it's again, it's a proxy of, you know, the investment and the time spent on the package. It doesn't necessarily mean that the packages with these badges are of high quality, but again, it's trying to show you what you should be looking out for if you're installing packages from GitHub. Excellent. So the other thing that I really wanted to cover very briefly is the idea of once you have an account, what you can do is you can star or you can follow other repositories for stars and other people for follows on GitHub. So you can see that up here, 19 people have starred the RobViz repository and starring is a way of essentially adding it to your own list. And so if I go in up into the right hand corner to my account, I can see my stars here. So if I select that, it'll show me the list. It should be quite long, I imagine it's in my big ugly mug. Then you can see the repositories that I've starred most recently that I think would be interesting me into the future. So it's a really easy way of keeping track of upcoming repositories that might not be on the list. It might not be widely available, but that you want to keep an eye on as things as they develop and it's a good way to just kind of collect things. So I have a lot of packages here related to work I want to do on RobViz at some point in the future. Excellent. And then the other thing is you can look at... How do I get there? Yeah. Oh, sorry, I've gone wrong. And the other thing you can look at is the people you're following. So if, for example, I wanted to follow Wolfgang, who I think is... I perform a search. It gives you all of these options for the search. So you can search repositories, code commits, but if I get into users, I find Wolfgang here, who's the author of the metaphor package for that analysis. And this is his user. Homepage on GitHub shows me some information about what he's working on at the moment and how to get in touch with them. So if I want to follow him so that on my own GitHub homepage, I'll see information related to what he's working on. I can choose to follow him. And so that just means when I go to github.com, any work he's doing will come up in all activity. So I'll be able to keep an eye on if he releases any information on if he releases a new version of metaphor, if he releases a new functionality, it'll appear there for me. So that really covers most of what I think you'll be working with as a consumer, what you'll be working with GitHub as a consumer. So just to move on a little bit in terms of if you actually want to start using GitHub to share your own code. So again, from the GitHub homepage, so github.com, you go to this little plus button and we're going to create a new repository. So you can call your repository pretty much anything you like and your repository name is made up of your own username, in my case, McGinloo, forward slash the repository name. So for example, we're going to call this esma or temp. And github will quite helpfully check all of your other repository names to ensure that you don't have any duplications and because you can only have one of each, they're meant to be unique. And you can enter an optional description. So temp for the esma or conference. You can choose to make it public or private. So public means that it's readily findable, it's indexed on things like Google. So if people are searching for your repository, they will be able to find it. But private means that only you and people you invite to the project are able to see it. So this can be quite important if you're working, particularly if you're working on analysis for an academic paper, you might set up the repositories private in the first place and then once the paper associated project is finished or the paper is published, you then make it public. So it's a way to kind of embargo your code and your work and your research until you're ready. And that's where the distinction between private and public. Another thing is if you're developing a normal package you need to make sure that it's at a stable working state before you release it more publicly. Setting it as private for the first little while as you get everything set up. And then once you're ready making a public sharing it on Twitter, doing that all together, it's a really nice workflow for kind of developing packages. So when you're starting a good, if you're starting an empty repository, a good thing to do is to add a readme file, which is what we were talking about earlier. So it provides some information when someone arrives at your repository and it provides some information about what it is and how they can install the package and how they use it pretty much. The other thing that's useful is to choose a license. Now I most commonly go for the MIT license, which is very permissive, but it just allows people if they come to your repository to know what they can and can't do with the code contained. And then you just click the big green button, create a repository and GitHub will set it all up for you. So we'll be able to see it now that again, we have the URL is github.com, my username, and then the name of the repository, which I've seen. So you can see that the description was copied into the little event section. If you want to edit this, you click the gear cog here and it'll give you some options. So you can add in, you know, I don't want to say this is for a conference. It'll pop up with a dropdown of potential options so conference, we'll just go with that. You can also add a website or rewrite your description and just save the changes. So this is your basic repository. And one of the most common things that people will want to do on a repository is to either flag something that they themselves have to do in the future, or if you're looking at someone else's work, tell the maintainer of that package that there's something wrong with their code or you'd like them to add in a new feature or just generally you have a query about something the package does. And the best way for it to do all of this is what's called issues. So if we go to the issues tab here, it'll bring us up saying welcome to issues. You don't have any yet because it's a brand new repository. That's not surprising. And what we'll do is we'll create the first issue for this. So you click new issue, again, the big green button. It asks you to provide a title. So here we're going to say my first issue. So here you can put pretty much everything you want, anything you want related to the package. So if you want to have a to-do list, cover issues as topic. GitHub is quite useful because you can use markdown formatting. So if we want to make this a checklist item, we can use this. Alternatively, we can use this button here, which is at a task list. So item two. If we want to see what it'll look like when it's finished, we click the preview tab here. And you can see that these are checklist items. So you can take them off yourself. So you go back to write and we'll just say item three. Yeah, maybe wrong. Yeah, item three. And then we're going to say submit new issue. So once you've submitted your issue, it'll appear again in the issues tab. It shows you what you said. And if other people, it provided your repository is public. If other people want to comment on your issue or say, I want to see this feature too, and they can leave their own comments below. So one common way of expressing if someone has said, I'd like to see this feature and you don't want to comment, but you want to show support, you can add little emojis. So upload or download or say that you're keeping an eye on this and you're watching. So it's just a way of interacting with people on the website. And along the right hand side provided your own repository, you can edit some of these things. So you can add a label. So you can say it's a bug. Something isn't working. You can say it's documentation. You're asking for more information or an enhancement. They're kind of the three common, or at least to my mind, I use the most three common labels just to let people know what category this issue falls into. And yeah. So issues are a really good way of capturing bug reports. Capturing tasks related to the repository. And they work very well within the GitHub setup. So the next thing we're going to talk about is branches and branching as part of working with code on GitHub. And branching is a really important part of developing code on GitHub. It makes part of what's called the GitHub flow, which is how software is developed using GitHub as the main platform to do so. And so essentially, the main concept is that within a GitHub repository, you can have a number of different branches. And so these are accessed for the repository in GitHub by viewing here. So you can see at the moment that we only have one, which is the main, excuse me, which is what would be expected for brand new repository. And the thinking on this approach is that anything on the main branch should be what's called deployable. So it should be ready to go. Users should be able to use it without any issues. And that all development work, anything that could break the package or the code is done on a different branch. So you have one branch going along where everything is working perfectly. You take a branch off of that to work on in terms of implementing new functionality that might be a bit touchy as you develop it. And then when everything is ready to go, you merge back in that development branch into the main branch, which now has the new functionality as well. And so what we're going to do is we're going to try and do this with something really simple. So we're going to create a new branch to make an edit to the read me. And then we're going to merge back in. So it's just to demonstrate the workflow. So for example, here, what we're going to do is we're going to call this and read me. The note of my typing is, it's truly terrible. It explains a lot of the bugs in my packages. So if you type in read me, because it doesn't exist already, it'll give you this option to create branch, read me. So if you click that, you'll see that the URL has also changed slightly. So we still have the base URL, which is github.com, my username, the name of the repository, but we now have this tree and read me this afterwards. So if you're on any branch, rather than the main branch, you'll see it here. So you're part of the tree, but you're on the read me branch. And github also gives you some information about how the branch you're currently on compares to the main branch. So you'll see here that it says this branch is even with main, meaning that there's no extra code or changes made to this branch that aren't reflected in the main branch. So we're going to make one of those changes now, just as an example. So we're going to try and add some extra text to the read me file. And we do this by clicking the little edit button here, which will bring us into the native github editor. So what we're going to just say is something really simple, like we're text to scroll down and we say commit changes. We add a little bit of information. So adding text. And then we want to commit to the read me branch. And then we commit our changes. Excellent. So if we go back to code, we see that we're still on the read me branch. And read me now has some new pushes or changes. And github is encouraging you to compare and open what's called a pull request. So pull requests are again one of the key parts along with branching of the github workflow. And so once you're finished making changes to your development branch, you can open a pull request. So that's what we're going to do. So at the moment we're on the read me branch still, but we're going to open a pull request now to ask the maintainer, which in the case of this repository is also us to pull our changes that we've made on the read me branch back into the main branch. So the main branch will also have this new information. So if you go compare and pull request, it opens this new format. And it shows you what branches you're comparing. So base here means the one that is there, the cornerstone or your main branch, but you can change this if you want. And then your comparison branches that read me, which is the one we've made an edit to. So we've added that extra text to. And the title is can be automatically generated or you can change it. And it's similar to working with issues. You can put extra information in here. And for yourself, 50 to reference or for the maintainer. So it'll also give you some information about the ability to merge the branches. And what this means is that there's no conflict or no conflictions. No conflicts between the two. So you don't have competing information in the two branches. And that can happen sometimes if more than one person are working on the package or the code at the same time. And all that happens then is you have to do resolve what's called a merge conflict, which means that you have to manually decide which of the two versions you want to keep. And again, it's quite straightforward to do once you're used to it, but I refer you back to that happy git with or book, which has some really great resources on it. So right, we're going to create this pull request. And we've added some information. And GitHub would check the ability to merge in the branch like we've been talking about a second ago. And once this gives you the tick, you can merge in the pull request. So this is again copying the information that the changes we've made to the read me branch back into the main branch so that it's available to other users from the main branch. So we go merge pull request. And again, I'd ask you to add any new information. It gives you a title. And then you can go confirm merge. And then you can delete the branch. So now that you've made the changes safely by branching off the main branch, making the change and then merging it back in. You can get rid of this extra development branch that you created so we can delete this here. Excellent. So we've now made a change to the main branch and we can examine that if we go back to code. And you'll see from the URL, but once again back on the main branch, which you see that the text that we added has now been copied across to the main branch via our pull request. You'll also see that because we've cleaned up our branches when we were finished, we no longer have the read me branch. And this is again just to really hammer it home a safe way to add new functionality and new changes to your repository without breaking the main branch and breaking the main version of the package. Excellent. So what have I left to cover? Yeah, so with pull requests, it's quite the example I've given you here is doing a pull request on your own repository. But when these really come into their own is when you want to make a change to another repository. So for example, if we go to again, we're going to go back to Wolfgang. So we go to the metaphor package by Wolfgang. And just as another example of a repository. So again, you can see the contributors down the right hand side. You have a little bit of information here describing the package and pointing you towards a website, but more information. And you have again the or CMD check passing saying that the build is working. You can see the huge number of downloads it has every month, which is another good time. Of quality and that people are using it on reporting too many issues. But say you wanted to make changes or contribute some code to this. So in order to do that, because you don't own this repository, you have to make what's called a fork. So you do this via the fork button up in the top right hand corner up here. So if you click fork, they ask you what account you should fork it to. So I want to. Copy to my personal account and it'll tell you that you're copying it across. We now have a copy of the metaphor repository on my own personal account. And you can see this based on the URL again. So we have my username rather than Wolfgangs and metaphor. And again, it's a similar way as if you created a separate branch within a single repository. It gives you information that it's even with Wolfgang. So any code I add to this will prompt GitHub to open a pull request. So again, for a very small example, just for the sake of. I'm going to add a small space just for something tiny. I'm going to commit the changes. And if I go back now, GitHub will tell me that I'm slightly ahead of the Wolfgangs main branch and will allow me to open a pull request. So this is a really nice way of adding in. New code to packages. And if you're interested in contributing to them. A good workflow generally is to open an issue on the repository you want to contribute to asking the maintainer if they're interested in you opening a pull request. So if interested in you. Forking their repository. And adding your code and then asking them to pull in the changes you've made. Before just randomly opening a pull request. But this is the way you do it. So it's a similar workflow. You fork the package. You add your code. And then you ask the maintainer to pull in the changes via pull request. Excellent. And then just one final thing I want to cover from the contributing level. Is that it's possible to. Copy the repository into our studio. And quite straightforwardly. So this big green button here. You click code. And you copy the link. Provided. So you click this button. Copy it. Then if you go to our studio. And go file. A new project. I don't want to say that. Or it's not playing nice. So it'll give you these options of how you want to create a new project. So the version. The option you're looking for. It gave the way that is version control. And get. Because it's a gift repository. And then if you paste the URL you've copied here. You'll see that it automatically populates the metaphor. Direct rename. And you can now choose to create the project. So I always open in a new session. But that's just habit. And you can choose where to create the project. And you can choose where to create the project. And you can choose where to create the project as a sub directory. So this is all assuming that you have get set up and you can interact with GitHub. But again, I'd refer you to the happy get with or. And book. Because it'll get you up and running with this. In no time. It's a really, really fantastic resource. And so what's happening now is that it's. The software is copying. GitHub. Or the metaphor repository from GitHub. To my local computer. Where I'll be able to work with it. Or to add new functionality. Or to make changes to what it already exists. So you can see that all of the files are now here within an or studio project. So it's just to show you how you can, you can work with that. And. Or how you can copy. Projects from GitHub. Across to. Or studio. Very. Straightforwardly. Nice. It goes all back down. Right. What am I missed. So. The final level of user that I just want to very briefly touch on because this will probably be. A very small minority of people is those who are maintaining packages. And using GitHub as a platform to do so. So there's three kind of main benefits. To this. And the first one is. Good. Book tracking. Again. Back to. Rob this. Which is my own. My own. My own. My own. My own. My own. My own. My own. My own. My own. My own. Back to Rob this. Which is my own package as an example. But a really good way of keeping track of what you have to do. What's not working with the package. And allowing other people who use your package to submit. Good reports or issues or problems. And is using GitHub issues. So here you can see the selection of issues that are currently open. Based on. currently open on the raw phase repository. And it just lets me know what I have to do rather than people sending me emails, me having to keep track of what different people are saying. So it's one of the major advantages of putting the code for your or package up on GitHub and allowing people to interact with us and report buggy issues all in one centralized place. And there are other options, but to me, I think this is a really great advantage of GitHub as a platform. The second then is what's called GitHub Actions, which is what gives this badge on the README, which is the orCMD check passing. So essentially it runs orCMD check, which is again, a collection of standard tests that all packages must pass or should pass. But it runs it automatically for your package every time you make a change. So it's a really good way of making sure, and it also runs it across multiple platforms. So Mac OS, Linux and Windows. So it's a great way of ensuring not only that every change you make doesn't break the package, but also that it works across multiple platforms, which is quite hard to test manually. So it's a really good resource. Again, this used to be managed by appliances or applications like Travis or App there, but it's all done in-house now by GitHub Actions and setting it up is really, really easy. And then the final thing that's really useful for package owners is the ability to set up an associated website with your GitHub repository. So if you go to settings and you scroll down to GitHub pages, it's simply a case of turning this on and pointing it towards where your website would be. A good option for building your package website is the package down or package. And it makes it quite straightforward to build quite a nice looking package. But GitHub allows you to serve this package for free with an associated link. So you can see here, this is the link to the other office one. And if we open it up, we should, yeah. Have quite a nice looking website that we can point people to and that contains a lot of the documentation and tutorials and change log for the RobFiz package. So again, it's an extra aspect of GitHub that really makes it a really good kind of holistic approach to sharing and accessing and storing all packages. So yeah, that's probably quite advanced and quite niche, but it's just to show you, if you are quite familiar with or developing all packages, that GitHub does have some aspects that can really help you out. I think that's it from me. I'm just reading through the last few bits I've meant to cover. I hope that's everything. I can't tell how long I've been here, my time abroad. But if people have questions again, please pose them to me to Slack or tweet at me. I'll just show this up while I'm talking. Yeah, please do tweet at me or let me know if you have any questions. I'm very happy to talk about any of this. If I've said anything wrong, feel free to point it out. I won't take any issue. I'm really glad to have so many people attending the conference and hopefully something I spoke about today will be of use to people. But other than that, wishing you a very nice weekend and happy coding.