GitHub.com Version Control Method

GitHub is an easy to use web-based Git repository hosting service, which offers all of the distributed revision control and source code management (SCM) functionality of Git as well as adding its own features. Unlike Git, which is strictly a command-line tool, GitHub provides a web-based graphical interface and desktop as well as mobile integration. It also provides access control and several collaboration features such as wikis, task management, and bug tracking and feature requests for every project.

Here is the real advantage: You can share your files and GitHub / Git will track changes you make and allow you to compare versions and make side branches to try out crazy ideas while still being able to return to the know working versions.

Other people can edit your files, but that doesn't change your file from /your/ point of view (unless they request a pull and you merge). From /their/ point of view, it does change your file and they can play with the version they made all they like. If they are happy with their changes, they can make a pull request and if you are happy with their changes you can merge them back into your project.

Git can be very very scary and complex, but getting started on GitHub is easy:

Author (Create new... New Repository)

It's easy to start a new repo and add files on GitHub, the hardest part is finding the little plus sign icon which is up next to your user icon in the upper left corner of the screen.

• Sign in or sign up for github. The first time you visit:
  https://github.com/
  it will prompt you to sign up.
• Create a new repository ("+" in the upper right corner, then New Repository)
• Name the repository. Enter a unique name (github will check) and decide what license you want and if you want to start with a README.md file.
• Click "Create repository"

Add / Edit

Simple text files can be edited right on GitHub. Binary files need to be downloaded (click the download button or "Download Zip" button to get the entire project, or click a file name then click Raw) or cloned locally with Git.

Review

Click "History" to see a list of all the changes to a file. Or the "# commits" list in the upper left to see all changes to the project.

Colaborate (Fork):

Browse through the existing repositories and click on the file names to see the contents. If you see some change you could make to a file, then

• Sign in or sign up for github.
• Fork the project. (Hit the "Fork" button, upper right corner) or a file (Click the file name on the left, then the pencil icon on the upper right)
• Open the file in your fork (click the file name on the left) or clone the repo to your local machine using Git)
• Edit the file to make your changes (on GitHub, use the pencil icon next to trash icon)
• When you are done editing, Commit your changes (scroll down, click Commit)
• Make a pull request. (green and white "New Pull Request" button.)
• Assuming your branch is now different from the authors (because you commited a change) you should be able to click "Create Pull Requst"
• The author will get the pull request and may approve it, which makes your changes the current "head" on this project and future forks.

This is using Github without installing Git on your local machine. It's quick, pretty easy, and... collaboration is fun and useful and worth learning to do.

Encouraging Colaboration

Add a CONTRIBUTING.md file to ask for involvement. In it describe how you would like others to contribute. You can point out areas were you will probably NOT welcome new code changes, and areas where you will. GitHub will add a "flag" on your main page with a link to "learn how to contribute" which leads to this file.

Actually assign tasks via github with "bitsized" issues to tell people what you want done.

• E.g. in firmware, raise an issue asking for someone to comment and explain your code. This is a wonderful learning experience for them and a benifit to future users.
• E.g. raise an issue for someone to review and edit any documentation. Not because it's bad or needs it, but just because it will encourage someone to go over it and suggest changes to make it better.
• E.g. Raise an issue for someone to develop a series of short examples that demonstrate how to use your code.

In each case, you are saying "We will value your contribution. We need this. We will actually use it."

You can also include checkboxes inside a single, more complex, issue as a way of breaking it up into smaller tasks which people are more likely to take on. Use this for your own internal TODO lists. Then YOU can check them off OR someone in the community can instead. Free help! See:
https://help.github.com/articles/about-task-lists/

If you need more complete project management, ZenHub and Waffle integrate tightly with github.

For user submitted issues, the template feature is very useful to ensure you get all the data needed to reproduce and correct the problem.
https://github.com/blog/2111-issue-and-pull-request-templates

Enable the wiki feature! It's a place for documentation of interest to the users.
https://help.github.com/articles/about-github-wikis/

Also, use the free github web page to introduce the open source side of the project.
https://pages.github.com/

See also:

• http://scottchacon.com/2011/08/31/github-flow.html A workflow for using Github

  .