How To Contribute
You may have noticed that we keep all of our source files on a website called GitHub. GitHub is more than just a place to keep your files, it’s what’s called a “revision control system”. GitHub uses a revision control software called Git. Git not only keeps our files, it also keeps track of every version of each file and who has made each change to each file. Git was created by Linus Torvolds (the creator of Linux) as a way to help the thousands of people around the world who collaborate on Linux to work together. Git allows multiple to edit the same software at the same time without stepping on each others toes.
The easiest way to explain how this works is to walk through an example. To encourage you to try this at home, I’ve created a file in the firmware repository called “guestbook.txt”. The guest book is a place to sign your name, or leave a message which will stay with the project. When you contribute, it also drives up the number of contributors on our page which makes us look cooler to other open source projects, so give it a go!
Until very recently Git was a command line tool which meant there was no user interface, but we’re going to be using the more user friendly GitHub Desktop application.
First, you will need to make an account on GitHub if you don’t already have one. To create an account, navigate to https://github.com/ and pick a user name and password.
Next, choose the free option. The company GitHub supports open source projects by offering all of their services free to the open source community. How cool is that?
Now you can claim a copy of the source code to be your own. This process is called “forking” because the software branches out like the tines on a fork. Your fork of the software is your space to experiment with it, change things, and hopefully make them better. Because this is your copy, you are free to experiment with the software in any way you want.
To create your fork, navigate to https://github.com/MaslowCNC/Firmware and click the “Fork” button in the upper right hand corner.
And that’s all there is to it you now have your very own version of the firmware, but it doesn’t do you much good when it’s only online.
To download the files to your computer we’re going to use a program called GitHub Desktop which you can download for free from https://desktop.github.com/. The GitHub Desktop software allows you to work on files locally on your computer and then synchronize them with the GitHub website. Think of it like Dropbox, but with more control over when files are uploaded and downloaded.
Once you have installed the GitHub software click the “Clone a repository” button in the lower right. Then click on “firmware”, then click on “Clone”. This will download a copy of the firmware to your computer to work on.
We’re going to edit the text file “guestbook.txt”, but the process will be the same for editing the Sketchup CAD files for the frame, the Eagle files for the PCBs or the text files for the software. Add any images which you would like to post in the wiki can be done in the same way.
I use notepad++ as my text editor so I’m going to open the text file there and add my message.
As soon as that file is saved, the changes appear in the GitHub Desktop application. To upload those changes to the GitHub website make a note about what was changed in the lower left, click the “Commit” button in the lower left and then click the sync button in the upper right.
This will upload your changes as a “commit”. Think of commits as save points. You can always go back to an earlier commit, so it’s helpful to commit often, but not so often that it is hard to tell your commits apart.
You repeat this process of editing files and committing changes for as long as you need to. When your changes are complete and you are ready to request that they be merged into the main version of the software click the “Branch” and then "Create pull request". This will take you to the GitHub web-page where you will have a change to review what changes were made and create the pull request if everything looks good.
The project will then receive a notification that a request has been made, and the changes can be merged in if they look good. Each pull request creates a space for the community to talk about what changes are made and they can be marked as approved by members of the community or linked to issues in our issue tracker system.
For a simple change like adding an entry into the guest book, this process is unnecessarily complicated, but when you have multiple people working on something as complex as a piece of software, revision control is crucial to that process going smoothly.
Git offers many many more features and benefits than we have room to cover here, but the best way to learn is by doing. As always, if you have any questions or we’ve missed anything, let us know in the forums.