Updated on October 20, 2014 with a little more clarification between New and Existing Projects, and links to the new meta project that I setup to capture requests for project inclusion.
You may have noticed that we keep all of our code on GitHub. While this is a relatively unfamiliar site to much of the manufacturing industry, it’s extremely popular and common among web developers, mobile developers, and all types of open source projects. Git itself is a version control system like CVS, Subversion, or Source Safe. GitHub just happens to be a very popular site that provides a Git server and additional features like issue tracking that open source projects often need.
Andy has already set up an “organization” on GitHub that hosts our various repositories. Each distinct project that we have started is its own repository within the organization. If you’d like to work on one particular project and not ALL of the code that we’ve started, you can just look at that one repository and not worry about the rest. You can browse all of the existing projects that we have started or have been contributed to the community on our Projects page. A simple guide to Contributing can be found in a meta repository that I set up.
If you have code that is an entirely new project and is unrelated to any of our existing projects, you have two choices:
- Create your own repository under your own account and we’ll add it to our Projects page.
- We can create a new repository under aaOpenSource for your code to live.
Either way, create a new issue here and we’ll take care of it!
- Check out an existing project, try it out, and submit any issues you find.
- If you have a solution, feel free to create a merge request and contribute back in to the code.
How to do a merge request
Creating a merge request is how you contribute back to existing code. Let’s walk through it and see how it works.
Let’s say that you notice an improvement that could be made with my project, aaTemplateExtract, and would like to submit a fix to it.
10,000 Foot View
- Make a copy of the code into your own online GitHub account
- Copy your online copy to your computer for editing
- Push the changes back to your own account
- Submit a request that the changes be merged back into the main code
Break It Down
- Download and install the latest GitHub client: http://windows.github.com/
- When you start the app, you can sign in using an existing account or you can create a new one.
- On the aaTemplateExtract page, click on the Fork button at the top right. This will copy the entire project code into your own account online.
- After it’s been Forked to your account, you can Clone this to your PC to start making the changes. From YOUR forked page, click the Clone in Desktop button on the right. It’s critical that we clone YOUR copy. So make sure that it no longer says aaOpenSource at the top and now says your user name and that it is a fork.
- GitHub for Windows will now ask you for a directory to place it. Select a good place you’d like to keep your working code.
- After it’s done Cloning, you’ll see the full revision history in GitHub for Windows and all of the source code is now on your own PC in the directory you specified. You can right click on the repository in the left-most panel and Open in Explorer to see the files.
- Open up the project in your favorite development environment, just like you normally would using Visual Studio or SharpDevelop. Make any changes you’d like to make, save, build, and test. Then, come back to GitHub for Windows to continue.
- Along the top you’ll see “master” with a drop down arrow. Click on it and you’ll see a list of Branches for this repository. There may not be any except for master.
- Master is the main stream of code that all approved changes get put into. If someone wants to make a change, they have to have their own Branch with their changes. When the Branch is uploaded, the person who made the change needs to send a “Pull Request” to the owner. This is just a notification to the owner to say “hey, I made some changes to the code base and I’d like for you to check it out and possibly include in the main code.” If the owner of the repository approves the Pull Request, then the Branch is merged in and becomes the latest master code.
- If you have a Branch of your own that you’d like to include this change in, then select it. Otherwise, create a new one by typing the name in the Filter text box and then click Create.
- You’ll notice that after you made changes you’ll have an Uncomitted changes panel above the History. Type in a good subject and description that explains your change, click Commit, then click Publish.
- Now, let’s go back to GitHub. On YOUR fork page, you’ll see that a recently pushed branch is shown. Click on Compare & pull request.
- If you’re ready to submit this code for review for the main branch, click on Create pull request. Be as descriptive as you can for the feature so that others can know what this is all about.
- Congratulations! You’ve submitted your first Pull Request to aaOpenSource! After we take a look at it, we’ll evaluate it for inclusion and approve or deny the request.
There’s lots more tasks that you can do with GitHub. I just wanted to get you started with it. Let me know if you have questions. I’m happy to setup a GoToMeeting to help out if you’re trying to contribute to the project. Definitely read and search the GitHub help, first, though, especially the GitHub for Windows help. There’s also GitHub Guides and a GitHub YouTube channel. Edu-ma-cate yourself, friends!