 Hi, my name is Alec, also known as Tech Trick. I'm sponsored by Adafruit to work on CircuitPython. And today I'm going to show you how to get started contributing as part of Hacktoberfest. So what is Hacktoberfest? Well, it's a month-long event sponsored by DigitalOcean, whose purpose is to improve and contribute to open-source software. Adafruit participates in Hacktoberfest across its CircuitPython repositories. So that includes the core, which comprises of firmware written in C for the microcontrollers, but also the libraries, which are a collection of drivers and helper libraries that allow you to interact with a bunch of different devices and services. So today I'm going to show you how to get involved with contributing to the libraries, but a lot of what I talk about will also pertain to the core. So I'm using Windows, so the process I'll go through is geared mostly for that, but all or almost all of it should also pertain to macOS and Linux as well. And I'll go over those differences when I can. So the first thing we'll need to download is Git. Git is version control software that allows you to do many things, one of which is work collaboratively with other people on software. If you're working on Linux, you likely already have Git. If you're working on Windows or macOS, you can go to git-scm.com and click on the downloads button and select your operating system. So we can go ahead and do that now. So open a web browser and go to git-scm.com and it'll bring you to the Git website. You can see here is the downloads button. You can select your operating system, so I'll pick Windows. And then most likely you'll want 64-bit Git if you're working on anything but an old computer. But you can check in your system settings, but I'll select 64-bit and that will start a download. I already have it here, I guess, from a previous download, but I'll save it again anyways. Great, it's downloaded. So I'll walk you through setting up Git and what you'll need and open that. You'll see a license agreement. So you can agree to that. And then for the most part, most of these default settings are fine. This is just where it's going to install. I already have it from a previous installation. That's fine, I'll just say yes. I didn't need anything else there. Calling a git in the start menu is fine as a shortcut. If you want to use a different default editor, you can select it, this isn't required, you can always use the text editor of your choice. I'm gonna keep Vim, this is fine. If you plan to use Git more, you can select this option to default the branch name to something else, but that's fine, we aren't creating repositories, so we can leave that. This default is fine to use Git from the command line. In fact, we definitely want this. Using the bundled open SSH is fine. Using the open SSL library is also fine. And then here's an important one. So we will actually want to select check out as is and commit Unix style line endings. So whenever there's a new line, Windows and Unix do things slightly differently because the repositories we're working with have the Unix style and we're going to do some things that later on rely on Unix style line endings. We actually don't want this conversion, so you can pick this and I'll walk you through one extra step just to make sure that that is fixed and we'll go over that in a bit. This default option is fine for the terminal emulator for the default behavior of Git pull. We want to keep this as the default, the fast forward or merge. If you've used Git before, you may want to choose this, but definitely the default behavior should be fast forward or merge if you're new. And then we want to keep this Git credential manager which just helps you with things like log-ons that we'll need later on and it handles that mostly in the background. And then these default extra options are also fine. And then we don't need any experimental options either. Great, and so now we're installing. And as soon as we do that, I'll go back and I'll show you how to make sure that those line endings don't become a problem during later steps that we'll talk about. Great, Git is set up and we're ready to go. I'm not going to view the release notes and we'll finish up. So in order to make sure those line endings are okay when we're working on them for later steps, you can open a command prompt if you go to your start menu and in the search bar just type in command prompt or even just the letter C-M-D together. It should bring up an option to pick the command prompt and you can just select that. And so I have here the command prompt that I was talking about. And so what we're going to do is fix that line ending problem so it doesn't become a problem later on. So if you type now git config dash dash global core dot auto CRLF input and hit enter, great. So that actually succeeded. So our line endings shouldn't be a problem moving forward. If you're looking for more information on Git or other parts of this process, you can actually check out the Adafruit Learn Guide System and search for a guide called Contribute to Circuit Python with Git and GitHub by Katni Rembore. And that's a great guide that goes over a lot of what I'll be talking about. But for now we're done with Git. So the next thing we'll need is a GitHub account. GitHub is a hosting service that hosts the repositories that we'll be working on. Adafruit hosts both the repository for the core, which again is written in C and all the repositories for the libraries written in Python on GitHub. So you'll need an account there to start making improvements. You can go to github.com and make an account or use your existing account if you already have one. If you're making a new account, you can choose the free plan, which has everything you need to start contributing. So we can go ahead and I'll bring that website up github.com, great. So I'm already logged in to my account, but if you need, you should make that account here. If you're using Windows or macOS, it's often helpful to have a graphical program known as a GUI to help you use Git. The simplest GUI program for Windows and macOS is GitHub's own program GitHub desktop. To download, go to desktop.github.com and select the download for your operating system. So we can go ahead and do that. So I'll open a web browser and type in desktop.github.com and that will bring me to the landing page where I can download. So I'll select download for Windows 64 bit, but if you're using macOS, you have a button for it right here. So I will go ahead and download. We will run that as soon as it's done, but this will make the process of using Git that much simpler. If you're using Linux, this may not be an option and you may need to be more familiar with the command line. I believe we have guides on the Adafruit Learn system. That will help you do that. So you can go to adafruit.com and select learn, button up at the top and find some guides on using that. But for now, since I'm on Windows, we will double click that to install and that should bring up a window like this. So let me know that is it installing. So there we go. So it may ask you for information on your GitHub account, which you should provide, because it will make a lot of the things we do here easier and in fact, I'm going to rely on them. So you should connect your GitHub account to GitHub desktop. If you need to, and it doesn't do it automatically, perhaps you've installed it before, you can go to options, I believe, and then here we go. And then you can sign in to github.com. So you can click this button and sign in. So if it doesn't do it automatically, that is how you can do it. The final thing we'll need is a text editor, something to actually edit the code with. The recommended text editor for CircuitPython is Mu spelled M-U and it has plenty of built-in functionalities for working with microcontrollers. To download, you can go to codewith.mu and download it there. So we can open up a web browser and type in codewith.mu and that will bring us to the website. You can click here, download, and select either the Windows installer or the Mac OS X installer. Additionally, it looks like there's experimental Linux support, but it looks like there's some notes here. So be sure to give this a read if you want to use Mu on Linux. So we'll select download and it may actually take a couple of minutes. So I pre-downloaded it and so I will open it from my downloads and get that started. And you can see here, it'll bring up a window. And I will agree to the license agreement and let that install. And then there's a couple things we'll want to do when it's ready. The great thing about Mu also is that there are plenty of guides on adafruit.com in the learn system. Specifically, I believe there is more information on welcome to CircuitPython is a guide about getting started using CircuitPython. And it actually talks about Mu, which is a great way to not just develop CircuitPython code, but also program your controllers to use it. So there are functionalities built into Mu for helping you do that. So if you need help with Mu, besides using the website here, you can also check out the learn guide system and find more information there. So great, it looks like setup is done. And we will launch Mu. So when Mu first boots up, it should ask you what system you're going to use. And there should be plenty of options, but you should see one that says CircuitPython and you should select that. It doesn't seem to have done it for me, even though I redownloaded it. Likely it remembers a setting I've had before, perhaps. But once you select that, you should get a screen like this. In case it also doesn't bring it up, you can always change the mode here with this button and your options should look something like this. So you should select CircuitPython and you should be ready to go. If it brings up a error box saying that it can't connect to something or to read the serial or something like that, it just means it can't find your microcontroller, which is fine, we don't have one connected right now. So no worries about that. Otherwise you're good to go with Moo. Now that we've got all of our programs downloaded, we are ready to register for Hacktoberfest. So you can make an account and register on hacktoberfest.com. So we will bring that up in a web browser. So we can hacktoberfest.com and select Start Hacking. So even if you've done Hacktoberfest in the past, you'll need to register every year, I believe, to do it. So keep that in mind. So you'll want to select Authorize with GitHub so that it can track your progress. So we can click Initiate and it will ask me to authorize Hacktoberfest, which I will select. And so you can have your name, your email. So make sure those are correct. I will keep these. And it should also show your GitHub user profile picture, which I don't have set. But if you do, it should be here as well. So we will be participating as a contributor, which means that we'll be submitting code and specifically pull requests. So we want to select this. If you were a maintainer, you'd want to select this. And if it looks like there's another option for Event Organizer, but these don't apply. So we will select Contributor. You can select your experience level. So either Newby, Familiar or Experience. So you can select your experience level. So I'll go with Experienced. What would you like to contribute? So there's code and there's non-code options, which is a cool feature, whether you are doing documentation or other things that aren't strictly code. It looks like documentation and design, things like that. You can select this. If you would like to do documentation for CircuitPython, that's actually part of our code. So you can just select code, whether you're doing bug fixes or documentation improvements, that will always be part of the code. So you don't have to select this. You can select the country you are participating from. There's operational opt-ins. So if you want to share your email address to receive some digital badges, I won't do this on this account. It looks like there are some marketing opt-ins. So if you want to share your email address and get some emails about different things, it looks like the sponsors, you can do that. I'll keep this checked. And then we can agree to the rules and terms. So all of these are great. A lot of these are just saying that you understand the rules of Oktoberfest that you're going to contribute quality code, that if you don't submit quality code, which is to say you submit things like spam or things that are malicious that you'll be disqualified, as well as that you understand the terms of service and privacy policy. So we will register and bam, we are ready to go. So now we can see our progress for pull requests and whatnot. You can see that so far we've got zero of our four done. So we will go look for some issues to find and fix. Let's get to it. So now it's time to look for some issues to fix. So how we'll be finding issues depends on where you're working. If you're working in the core, you can find them in the core repository, which is github.com slash Adafruit slash CircuitPython. And there is the issues tab there that will show you a list of issues. But since we'll be working on the libraries, we'll go with the other way. So to find issues in the libraries, we can open up a web browser and go to circuitpython.org. And this will bring you to the CircuitPython landing page. And what we're looking for is this button here called contributing. So we can click on that and we'll select open issues here. So what this will do is show us a list of all the different issues across the library repositories that we can select and read more about. And the nice thing about them is that a lot of them have tags on them that kind of tell you a little more at a glance. So you can already see some of them are labeled Hacktoberfest, which means they are counting towards Hacktoberfest. And the one we'll be looking at is ones that say good first issue. So things labeled as a good first issue are great if you are new to contributing and you are looking for something that is at that skill level and that's a great place to start. So we will look at one of those and I already have one in mind, but feel free to look through these and kind of read about them at a glance. The one that I will be working on is this one. So requirements.text is missing Ada Fruit Blinka. So I'll select this one, but you should go with whatever one you want. So you can see here it's a good first issue as well. So we will select this and what that will do is it will bring us to the specific repository and show us the issue we clicked on. And so now we can actually see a little bit more about the issue. So this one looks like it's missing something specific in a file called requirements.text and here it also lists the solution. So all we need to do is add this to the file. So you can also see history here. I opened one earlier, but wanted to use this for the example. So I ended up closing it. You may or may not see this, but if there is a history attached or other comments or information, you can see it here in the first or following comments. So if you wanna take this one on, you can just start working on it or another thing you can do is just leave a note. So what I'll do is I will leave a comment just letting people know that I'm going to work on this and that isn't required. You don't have to do that, but what it does is it lets other people who might find this issue know that you've already got it covered. So they don't accidentally work on it in parallel and they can find something else that needs to be addressed. So this is the issue we're going to stick with. So we can remember it and remember this repository. So Adafruit, CircuitPython, ColorSys is the repository I'll be working on. And so we can get started making this change. Great, now we're ready to start working on this issue. So in order to do that, the first thing we'll need to do is to fork and clone this repository. So forking is taking this repository, which is now under Adafruit and making a copy under our name so that we can start working on it. So I can't directly make changes to this one that Adafruit owns. So I will make a copy of it so that I can. And what cloning is, is a fancy term really for downloading. So I will download the repository to my computer so I can work on it there. So let's get started with that. So in order to fork a repository, there's a button here called fork. We can click that and it says here, create a new fork. These options as the default are great. So we will click create fork. And now what you'll see is the same repository under my name. And you can see here, it'll say forked from Adafruit and then it'll list the repository name, which now means that they're linked that will make use of that later on. So this is great. And so now in order to clone it, we can open GitHub desktop and we'll select clone a repository from the internet. And the option we want selected here is github.com. And since we've linked our GitHub account to it, it knows which repositories we own. So it knows that we've done this. So if you need also, you can refresh this list. So we can select this and this local path just shows where it's going to download. So I'll have it download this to my desktop. And I can go ahead and click clone and great. Then the only last thing we'll need to do is select one of these two options. The one we want is this first one to contribute to the parent project. So what this is saying is that our goal for why we cloned this repository is that we want to eventually add these changes to the parent repository. So we'll keep that selected and click continue. We can hit this button fetch if we want to make sure everything's up to date. Great. Now we are ready to move forward. The next thing we'll want to do is to create a branch. So you can think of a branch like an individual state of the code. So we can make changes to it. And any changes we make in one branch in a repository exists separately from the others. So it gives us the ability to start making changes without affecting anything else. Any other changes we might make in other branches. So what we'll want to do at this point is make a new branch to start working on our changes. So if you go to this button here, it should say main or something like that and select it. You'll want to click this button for new branch which says we want to make a new branch. And what it'll say here is your new branch will be based on the repository's default branch. And it listed here as main. And so what that means is that we're basically making a copy of this branch. So, which is what we want. Typically for the sake of what we'll be doing, typically want to make it off of the default branch. And so now all that's left is to give it a name. So for my issue, I'll call it add dash missing requirement and you can name it anything. And I'll click create branch. And you can see here, now this says add missing requirement. And then what we can do here is select publish branch. And this will tell GitHub that we have a new branch. And if we wanted, we could actually see it on the website at this point. And so now it's time to actually start editing the code. So now we're ready to make the actual change according to the issue. So if we go to the issue again, we can see that we need to take the file named requirements.text and add this line, Adafruit dash Blinka to it and that should fix the problem. So one thing I'll note is that I will not be using move for this specific issue because move is really intended for Python files and this file is a text file. So I will actually be using a different text editor, but if you are working on a Python file, I would encourage you to use that since it will be a little bit better suited for what we're working on. So I will go to here, GitHub desktop. And if you select repository and show an explorer, it will bring up on Windows at least a the location of your downloaded repository in the file explorer. And so I will go scroll down to this which is the file I need. So I will open it for the sake of simplicity. I will double click this and it should bring it up for me in notepad. So I'll close these windows just to make it a little more visible. And so what I'll do for this issue is I will add that bit of text. So I will write eta fruit dash blinka and I will save. And so if we go back to GitHub desktop, right, we can see that it recognizes a change in the code. And so what we can do at this point is add and commit these changes. So adding a change tells get specifically which files or which lines you'd like to prepare, right? So I can select whole files or individual lines. And committing means that I'd like to make them a part of the official history. You can think of it of the branch. So if I go in this branch, right, I go to this button here, history, I can see a list of all these different commits that are a part of this history. So what we wanna do is we wanna add this add on top of that history. So I'll go back to changes and this is a pretty simple commit. So I will just add all of these, keep these selected. But if you're doing something more complex, feel free to break it up. And for committing, I will add here in this box here a commit message. So I'll say added Adafruit Blinka as requirement. And if it were something maybe a little bit more complex, maybe the commit message isn't enough, you have another box down here for description. So you can add a little bit more information. Since this change is pretty simple, I won't do that. But if you are making a more complex change, feel free to use it. And so I will click this button, commit. And if we go to history here, we can see that we've added this commit on top of the existing history and we are just about ready to upload it. So before we upload our code, we can run things like linters and formatters on it to make sure it's following best practices and that it's consistent with the other libraries. Additionally, when we upload this code to GitHub, GitHub itself will actually run these same tools on the code we submit. So we want to make sure that when we submit it, it will pass those processes. So in order to run those tools, there's actually another tool we're going to use called pre-commit, which manages running all of those tools. So it's important to note that at this point, if you have not downloaded Python, you'll want to go ahead and do that. I won't go over that process, but there are plenty of tutorials on how to do it for your operating system. If you're on Linux, you likely already have it as well. So you can pause here and come back once you have done that, if you have not. Otherwise, we can install that tool. So if we go here in repository again, and we click this button, open in command prompt, we will actually get a terminal window that is pointing where our library is. So what we can do, and I'll close these other windows for now. So what we can do at this point is actually install the pre-commit library. So what I'll do is I'll type pip install pre-commit and hit enter. And it's a little bit faster for me since I already had it on my system, but if not, you may see something different. But what we're looking for is just a successful installation. So we have that here. So what we can do now, if you want to clear your screen by the way on windows specifically, you can type CLS and hit enter and that will clear your screen. So now what we can do is we can actually run the tool pre-commit to run the linter and the formatter. And the great thing about pre-commit and the tools we'll be running is that it will either tell you where your code needs to be fixed with line numbers and the linter will tell you the specific problem. But for the formatting, it will actually fix it for you. And then what you'll need to do is just add those changes as well as the changes you make from the linter's feedback, you'll want to add and commit those as well until you pass the pre-commit process. So to run that tool, we can type in this repository, pre-commit space run space dash dash all dash files. And what that will do is run the tool on all of the files in this repository. So we can hit enter and we'll start seeing the process work. And what you can see is that for a lot of these, it has passed. So our black, which is our formatter, has passed. Some of our other tools have jumping ahead. We don't have any test code is what it's called here. So it has been skipped. But what we notice here is this fixed end of files actually failed. And if we read here, right, it says files were modified by this hook and it says fixing requirements.text. So what the pre-commit program did for us is actually fix the problem for us. And if we go back to GitHub desktop, what we can see here in the changes is this change here, which basically means that a new line was ended. So if we open our code backup, right, this is where this is the last line when I added it. But if we go, maybe this is the wrong file or reopen it perhaps. So we go back to our requirements.text. And open it again. So it reloads. What we can see, right, as before on the other one, before I reloaded it, this was the last line. Now you can see it added a new line. So we went from here to here. And that's just best practice. You typically want to end your files with a new line. So pre-commit, notice that we hadn't done that. And it went ahead and did it for us. So now all that's left to do is add and commit that change. So we can close these windows and come back to here. And we can keep both of these, right? So the deletion line matches the addition line. So we'll just keep both of those. And so they're added, they're ready to go. And we can say, re-formatted by pre-commit. Or we could say added new line or anything like that, just to convey the message of what happened here. So I will commit this change. And again, if you go to the history, you can see that change on top of our other one. And we are going back to changes and we are ready to push the code to GitHub. Great, now we are ready to push the code to the server. So we can check one final time just to make sure. So if I bring up the command prompt again and type pre-commit space run space dash dash all dash files and hit enter, what we want is for everything to either pass or be skipped if it isn't necessary. So because we went ahead and let pre-commit fix this, for us, the next time we run it, we can see that it isn't a problem anymore. And we've committed that change, so we are ready to go. So going back here, what we can do is we can click this button here called push origin. If it says something else, make sure that you are on the branch, right? So I'm on my add missing requirement branch. And if it says publish branch, if you haven't published the branch prior like we did here, you can always check the history here and see if these changes are ready to be pushed for your branch. So we will go ahead and click this button. And we can see that it's uploading and great, we are ready to go. And what we can do is if we go back to GitHub, right? And then if we're on Adafruit's repository right now, right? We can go to this arrow button on the fork button and click ours. What we can see is that our branch has been uploaded and that it knows that we've made pushes, right? We've uploaded code to it recently, less than a minute ago, so just a moment ago. And we can either create a pull request here or do it in GitHub desktop, which is the next thing we will talk about. So now that we've pushed our code, we can create the pull request. So you can either use the button I previously showed or if you go back to GitHub desktop, you should see this button here that says create a pull request from your current branch and it has the branch that I was working on and I'm currently on and I can select this button. So creating a pull request is basically a formal request to Adafruit, the Adafruit repository, saying that you want to add the changes that you've made in your own repository and you want them incorporated there. So that is the process by which we will introduce these changes. So I have clicked that button and it takes me to a page in the Adafruit repository called open a pull request. So you can see that I am using my repository, specifically the branch that I selected and we're going to merge into the main branch, the default branch in Adafruit's repository. And so if you scroll down, you can see a list of all the changes we made, right? So this is a list showing the changes and this is a list of commits we're going to add. So what we can do if all that looks good is we can add a message here. So if you have multiple commits, this may look a little funny but it may populate like mine has with a message. If not, we can type something. So add missing requirement, Adafruit, Blinka just to reference which one it is. And then for the comment, we can add a little more information and a really neat trick here is that if we want to link this pull request to the issue we're working on, we can use what I think GitHub calls magic keywords and so there are a couple of them. The one we'll use is the word resolves and if you type resolves and the issue number, it will link that. So if we go on this other tab, our repository, if we go back to the Adafruit one and we click on issues and we go to the issue here, you can see this number right up at the top is the number we want to use. So we will remember this 23 and it will be different for your issue and go back to our pull request and we say resolves pound 23, and it knows that you're trying to link. You're referencing a pull request or issue so we're referencing an issue. Resolves number 23 by adding the missing requirement. All right, so we've got our message, we've got a little description that adds some more detail and we've got resolves number 23, which will link it and now we can create this pull request. And so now a couple of things will happen at this point. So we can see that we have created the pull request. We're in Adafruit's repository and if we actually reload this page, we can see that this is updated and it says first time contributors need a maintainer to approve one in workflows. So what this is is what I was talking about before where the GitHub will actually run things like the linters and the formatters on your code to make sure they're consistent. If you're a first time contributor, you'll likely see a message like this which just means a maintainer will need to come in and just manually approve that. But if you're submitting multiple pull requests and you're not a first time contributor, it should automatically run. And so typically this will take a few minutes and you'll either get a green check mark similar to this or you will get an X and that will just signify that your code has some issues. Maybe it needs to be reformatted or maybe the documentation didn't build or things like that that were an issue. And so at that point, you can go ahead and try running pre-commit again. That is usually one of the more common problems. But if you're having trouble understanding kind of what went wrong or what needs to be done to fix it, feel free to leave a comment just asking for help and we can walk you through that process. So I don't have it here at this point but once your pull request passes the continuous improvement, the linter and formatter and automatic things like that, this will be green and there are no conflicts with the base branch which just means that it is otherwise good to merge into the main repository. The remaining and final step is to receive a pull request review where someone will take a look at the code and a couple of things might happen. Either they will say, great, this is exactly what we're looking for. Thanks. They may leave a comment asking for a little bit more information. Maybe they have a question or they're unfamiliar with something or they may request changes which maybe they noticed a typo or maybe a specific way you implemented something won't work for Circuit Python or things like that and at that point what will happen is you'll need to make changes to your code to better suit those requested changes so you can go ahead and do that and make those changes and add and commit them and repeat the process or of course you can always follow up and ask any questions you have or things like that so that that is clear as to what needs to happen next but otherwise this process repeats until the pull request is approved and at that point if it's approved a maintainer will merge it in to the code and at that point you can go look for another issue and start it all over again. If you need help with your specific issue or pull request feel free to leave a comment there so we can get started helping you out. Additionally if you're looking for help on a specific topic feel free to use the Adafruit learn system to find more information so you can find that if we open a web browser and go to adafruit.com and go here to learn up at the top and now we can use this search bar to start looking at learn guides. So one I've mentioned is one by Katni called contributing right and you can see it here. It's called contribute to Circuit Python with Git and GitHub and you can click this and it will show you a whole bunch of information or you can look by topic. So we can go here and type Git and we can find a whole host of guides pertaining to Git and various things there. So if you have a specific question on a topic feel free to check out the learn system. A lot of what I've talked about either is contained there or comes directly from there so I would encourage you to check this out if you're having a specific problem. The answer may already be here but if you're looking for help with something not listed here or it's more general maybe it's about Hacktoberfest in general feel free to reach out in the Adafruit Discord server which you can join by going to adafru.it and that will allow you to join the Discord server. So you can see that here I'm in the Discord server and if you scroll down there's a channel here called Circuit Python Dev this is where the developers of Circuit Python will mostly hang out and respond to messages but if you have a question specific to Hacktoberfest feel free to click up here in the threads button and find the Hacktoberfest 2022 thread and you can select this and if your question is about Hacktoberfest in general this is a good place to ask about it so that we can better find it and respond to it. Thanks for watching. I hope you're feeling ready to start contributing to Circuit Python as part of Hacktoberfest. It's certainly one of my favorite times of the year as it's when I started first contributing to Circuit Python. If you have any more questions feel free to reach out on the Adafruit Discord server and we'll get back to you as soon as we can. Thanks and we'll see you very soon.