Or An Introduction to Github.
By the end of this tutorial you'll understand how Github works, have setup and account and cloned the GMSN repository. You'll also be able to submit updates back into the master for GMSN! or any other Open Source synth projects.
So Github? What's that all about?
Github is basically just a collection of text files, with some funky features to assist with collaboration. These text files are what you use to write code. The GMSN! Repository is a collection of Arduino Sketches for the Pure ADSR, Pure Quantiser and Pure Sequencer, all of which are based on the ATMEGA328, the same chip as the Arduino. This means you can use the Arduino IDE programming environment and libraries to create code for these modules, or modify the code from the GMSN! github repository.
Clone the GMSN Repository.
This will copy all the GMSN! code to your own computer, which you can then open in the Arduino IDE.
- Go to the GMSN! Github Repo
- Click on Clone or download, then Open in Desktop. You can also just Download Zip, which will mean you can copy the code, but you'll miss out on some of the collaboration features required later on.
You should now have a local copy of the GMSN! repository on your computer.
- Open up the Sketch in the Arduino IDE and you can start making changes. If you went for the Github Desktop route, any changes you make to the code within the will be tracked.
- Make some changes to the code in the IDE.
- Go back to Github Desktop and you can see how the changes have been tracked.
So just to summarise where we are... you've created a Github account and cloned the GMSN! repo to your desktop, which you've opened in the Arduino IDE. You can now make changes and use this code in your own modules. But what if you want to contribute a bit more to the Open Source movement?
Creating your own Github Repo
The next step is to create your own repository on Github. You will then be able to keep your local copy in sync with your own master, then send a request to have your changes pulled back into the GMSN! master. For example you might have coded an awesome new feature for the Pure Quantiser or improved the attack cycle on the Pure ADSR and you want to share this with everyone else.
- Ensure your logged in on Github.
- Go to the GMSN! repo and click on Fork.
- This will copy the whole repo into your own account. You'll see in the top left that it's now in your account and it also shows where it was forked from.
- The next thing to do is to clone your new repo into Github Desktop. You might want to tidy up the files from earlier at this point, just to keep everything organised.
- Now when you make changes in the Arduino IDE, you can see them tracked in Github Desktop
- Now you can commit the changes you've made to your master copy. You'll need to enter a short summary of the changes you made, then click on Commit to master.
- This will only commit these updates to the local copy, the next step is to Push these back up your repo on Github. Click on Push origin in the top right. The changes will now be incorporated into your repo.
Request your changes be pulled back to the GMSN! Master.
This is the fun bit and the whole purpose of Open Source and Github. Two brains are better than one and by sending your updates back into the Master means that other's who are developing can benefit from the whole group's work.
This is done by creating a Pull Request
- Click New Pull Request. This will take you to a page where you can review the comparison between your file and the master. It will probably say something like "Can't automatically merge" This is a good thing, as most people will want to review any changes people make to their repos.
- Click on Create Pull Request. You can now give it a short title and a description. Try to be short and concise, but include as much detail as you can. Don't shy away from technical jargon, but don't feel the need to explain everything. If the reviewer doesn't understand a term, they can always do a quick search. Also ignore any self induced pressure about sounding like a newb or not coming across like a subject matter expert. The important thing is to kick start the conversation about why your awesome new feature needs to be included. I'm actually dying to see what people do with the existing code :)
Wahoo! We've now collaborated on a Open Source Project! Get in!
That's really all there is to it. Github is just a collection of text files with some funky features for tracking changes and keeping everything in sync.
If you really want to get involved in developing the Open Source modules, check out the Issues page for stuff that needs to be done.
If you've any questions on this tutorial or want to chat about potential updates, hit me up on the GMSN! Slack.