Getting Started with GitHub

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.

New Projects

If you have code that is an entirely new project and is unrelated to any of our existing projects, you have two choices:

  1. Create your own repository under your own account and we’ll add it to our Projects page.
  2. 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!

Existing Projects

  • 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
  1. Make a copy of the code into your own online GitHub account
  2. Copy your online copy to your computer for editing
  3. Push the changes back to your own account
  4. Submit a request that the changes be merged back into the main code
Break It Down
  1. Download and install the latest GitHub client: http://windows.github.com/
  2. When you start the app, you can sign in using an existing account or you can create a new one.
  3. 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.
    • Fork Button
  4. 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.
    • Forked Copy
  5. 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.
  6. 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.
    • 2014-10-07 15_31_12-GitHub
  7. 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.
  8. 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.
  9. 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.
    • Branches can be named anything, but the convention is to give them a somewhat descriptive title for what the purpose is for, often using prefix verbs such as “add” or “update” or “cleanup”. For instance “add/featurex” would be a good branch name.
    • Adding a Branch
  10. 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.
    • Committing to Branch
  11. 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.
    • Compare pull
  12. 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.
    • Submit Pull Request
  13. 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!

9 thoughts on “Getting Started with GitHub

  1. I like this initiative for building open source tools around ArchestrA. My biggest suggestion:

    Create a CONTRIBUTING.md file in the repositories, and come up with a consistent style guide for the projects. From what’s up there right now, it’s fairly inconsistent, so I wouldn’t know what style to contribute in, and aaEncryption project doesn’t appear to follow C# style guides (c-prefix on classes looks more like C++, no ProperCasing on class names and some methods).

    You may want to yell at Andrew about some of his commit messages too:
    https://github.com/aaOpenSource/aaBackup/commit/1af6fd348d446204fa294945a8dbda317ea5edde
    https://github.com/aaOpenSource/aaEncryption/commit/7e776ceb6429ffb6477fffad24c78562dc5be389
    https://github.com/aaOpenSource/aaBackup/commit/c845dcc2a744833854296a6e3d8d640401613e48 (my personal favorite)

    I’ll definitely keep an eye out and may start contributing soon!

    1. Will, thanks for checking out our progress! I hope you’ll contribute!

      Thanks for the suggestion on a CONTRIBUTING.md. I’m pretty new to administering a GitHub project, so I’m trying to learn as quick as I can! I’ll work on getting this added ASAP.

      Have you seen any examples of other projects that point/link to many contributors code? I am trying to figure out the best way to point to, say, this ArchestrA Notepad++ plugin. Forking it to our repository adds unnecessary overhead (I have to update the fork whenever he makes changes in his repository). I’m still playing with the most effective way to be a directory of code. This is a good problem, though! 🙂

      Ok, Andy, time to beef up your commit messages…..

      1. If you’re not actively maintaining changes to the repository, then you shouldn’t fork it.

        Generally, I’d say that’s either better reserved for a website front-page, or some kind of default repository with a list of all projects in the README.md, Github Wiki, or Github Pages ( https://pages.github.com/ ).

        An example of a README.md: https://github.com/karan/Projects-Solutions

        Any of them really achieve the same end-goal. The wiki is likely the easiest to edit and maintain (no commits required), and the README.md would just have a link saying to look at the wiki. The Github Pages or website meanwhile have the potential to look better and get more traffic from Google.

        1. Good point about forking.

          I’ve definitely been leaning towards setting up a page here on this site. Andy and I were talking over the weekend about setting up a page here that lists the projects, the descriptions, and a status. That way we can control the organization of the list and provide more context than the GitHub list of projects can.

          Thanks for linking to that Projects Solutions. There’s some good examples in there of how we could do Contributing too. It’s hard to find examples like that from just browsing around.

          Let me know if you have any other ideas for how we can best collaborate. I really appreciate hearing from others on this.

          1. Also, I will update this Guide as needed. This has been exactly what I was hoping for… a discussion starter on how best to do all this!

  2. (Andy) hangs his head in shame…I must say that these first projects are just a way to get some kind of a seed for people to congregate around and start to make their own contributions. They are built for purpose code sets that I have put out for others to use and or improve upon.

    I do agree that my commit messages must be better… and I think that is going to start with learning how to properly use GIT. I’m still struggling with those basics.. and my lovely friend Eliot’s guide will hopefully help me out. Maybe I can be an inspiration to all those out there who have no clue what they are doing but just want to pitch in. If I can do it, then they can do it also. Then we can depend on the experts to keep us between the ditches and teach along the way.

    -andy

    1. Thanks Joe. We have been in touch with Ryan and Eliot has linked over to his work in our GitHub. This is a great example of what we are trying to buld. Eliot and I only have so much brain power and time. For this community to be successful we will lean heavily on a lot of different people making contributions.

Leave a Reply