Improve the world through sharing your code. Participating in a community of coders brings professionalism to your hobby. The Arduino world is a community that values the free flow of knowledge and recognizes the benefit of the community to problem solving.

While sharing code might seem to be an unsolvable puzzle at first, many tools have been used to accomplish the task of code collaboration. In this chapter, you will learn to use the online code-sharing community called GitHub. Along the way, this chapter will also explore how the Arduino open source community uses modern social-coding practices to contribute to projects.

Social coding is the idea that any code you create begins with and contributes to the work of a community of coders and active users who want to assist you as well as to improve their own projects.

Arduino is a fast-changing platform, and its development and best practices are set not by industry standards alone, but also by the emergent interaction between industry makers and an open source community of software and hardware hackers. How you participate in the open source community demonstrates how you are a professional. In the field of Arduino and open hardware, pro means using emergent techniques in social-coding communities, alongside making and testing in open, entrepreneurial communities. Open hardware, like open source software, even if created by a single person, is used and lives on in communities of use. So contribute your Arduino IDE source code for the good of the world and move along.

Because Arduino is open source, it is always under revision by its community of developers. Your code can undergo quite a bit change when starting a project, and when people begin to work collaboratively with you. The fast pace of change in a project needs to be matched by fast updates to the documentation. You and your collaborators will all need to have the same shared idea, and learn to describe that shared concept via documentation in a collaborative wiki environment. Even if you work alone, documenting your process will enable you to quickly return to projects once set aside, keep track of multiple projects at a time, or publish the software to run a kit you want to sell. To document your project, you need to know how to create pages, and edit a project Wiki using the Markdown syntax. This will be covered in the Documentation section of this chapter.

Components of Social Coding and Project Management

Project description, issue management, code version control, and documentation are the main components of social coding and project management. We will dig into each one, including a description of what each is and how you manage it through GitHub. Instead of these features all being hosted in different systems, they can all be found on GitHub. Centralizing these features in one place helps your community of users and developers keep up to date with the project and automatically watch for changes. The project repositories you host at GitHub can be created as public or private repositories. You choose whether you are hosting a private project for a small team, or a public open source project. On GitHub, you can host as many public open source repositories as you like, but you have to pay for the ability to have a private project.

The first example in this chapter will be a Hello World GitHub example that you can use as a template for structuring typical projects. All the examples for the book will be organized in a GitHub project repository: http://github.com/proard. As we learn the tool, you will be able to not only get your own copy of the code for the book, but you will be able to submit your changes back to the main project.

Version Control with Git and GitHub

This section will provide one way to set up your development environment using Git and GitHub. It will drill into the details of how to perform project management in a social-coding world. GitHub at its core is the code repository that allows for version control.

Version control, or revision control, tracks every change made to software, including who made the change and when it occurred. This allows for multiple people to work on software simultaneously and merge the changes into the master code base. The tool at the heart of this is Git.

What Is Git?

Git is a powerful version control system that is used with many open source projects, including Linux Kernel, which has thousands of contributors and projects. Among the projects tracked with Git are Arduino software projects and projects from Adafruit Industries. The Git tool, which is a version control system that is completely distributed, allows for a massive amount of code hacking by multiple developers across the world. Everyone with a copy of the repository has a complete copy of the entire project with its entire revision control history. What is really unique with this is that developers are encouraged to fork the project and make their own changes to it.

Each copy of the software is either a clone or a fork. A clone is a copy of the master online repository on http://github.com/proard/hellogithub; you will use a clone of your project locally on your computer.  A fork is an online official copy of the repository, one that you maintain on your own GitHub account, at http://github.com/youraccount/hellogithub. Git allows for a highly trackable and secure communication process between repositories. You can send cryptographically signed changes between you local repository and your remote repository. This supports secure development and accountability for who, where, when, and what changed.

Here, I will cover the basic starting commands and the preferred development process supported by the Arduino community. GitHub provides a nice starting guide at http://help.github.com, as well. The steps presented here will be similar to those from the guide, but they will be geared toward starting your own Arduino projects.

Installing Git

First, you must install Git locally and create an account on GitHub. Check out the “Get Started” section on GitHub, at https://help.github.com/articles/set-up-git. The command-line version of Git can be obtained from http://gitscm.org/ and should be installed as you would any software. I recommend selecting the shell options for Windows. The Git shell makes it easy to access Git on the command line. There is also a GitHub GUI tool for managing Git repositories which is helpful, but not a replacement for all of the features that come with the Git command line software.

One additional feature of Git is that it is cryptographically signed, and every commit and change clearly trackable, and makes programmers accountable for the changes they make. You will need to configure a unique key for your system. To get started, you’ll need to do the following:

• 1.  Install Git.
• 2.  Create GitHub account at http://github.com.
• 3.  Generate a key pair to authorize your commits.

• Mac OS X: Go to https://help.github.com/articles/generating-ssh-keys#platform-mac
• Linux: Go to https://help.github.com/articles/generating-ssh-keys#platform-linux
• Windows: Go to https://help.github.com/articles/generating-ssh-keys#platform-windows

• 4.  Set your user and e-mail in Git at http://help.github.com/git-email-settings.

Here is the command-line option for setting your global user information:

$ git config --global user.name "Your Name"
$ git config --global user.email[email protected]

With these settings in place, your system is ready to start working with the Git repositories, and GitHub. Your system will now properly indicate the code changes you make, and the changes you submit will be cryptographically accountable. This makes working with GitHub seemless.

GitHub Tools

Now that you have Git installed, and a GitHub account, you have your own area for repositories and account management on GitHub. I prefer to install the Git command line software prior to the GitHub GUI tools. That way, there is a command-line tool and GUI access for your project files. This lets you experience the best of both worlds.

Figure 2-4 shows the GitHub GUI configured to display projects on the local system. This shows your repositories and what organizations they belong to, as well as their overall status. It is possible to drill down into each project and examine individual files. Importantly, the Git GUI will generate the security keys for you.

You are now up and running with GitHub. GitHub GUI will list your repositories on GitHub and synchronize changes from both your local repositories and your GitHub repositories. It provides a nice level of convenience, but learning the command line version of Git will offer better access to the revision control features, and showing the code differences between versions.

Version Control, Basic Workflow

In this section we introduce a basic work process for version control. This starts with creating your own example project in GitHub, then expands to working with projects other people have created, and then reviews the necessary Git commands that allow you to manage a version controlled project. This includes finding out what changed, and moving your code from your local repository to your remote repository on GitHub. It is possible to have more than one remote repository, but for this chapter your repository on GitHub will be the remote repository we use.

From Figure 2-6 you can clone the project locally. By cloning the project, you are in fact downloading the repository from GitHub using the “git clone” command. This is your copy of the entire repository on your local computer. Cloning can be done with the GitHub GUI application or on the command line, as follows:

$ git clone[email protected]:username/HelloGithub.git

In this case the “username” is your username on GitHub, and the command will copy all the files and version control information to your local machine. This is your local repository; all changes stay in the local cloned repository until you push your changes back to your original online repository on GitHub. “Origin” is the official name for your repository on GitHub. Your local code changes do not automatically move to the “origin.” You will have to “push” your change to your origin. Also, changes that you edit online directly to your GitHub project or if new code is merged into your GitHub project from other code contributors. Those changes have to be “pulled” to your local repository.

Editing Code and Checking for Changes

Once you now have a complete copy, or local clone, of your project, the process of working with and modifying code begins. Through the work process you will manage the changes to the project, and eventually send those changes back to your remote repository at GitHub. You will need to know how to check to your project for changes, commit those changes, and send them back to you GitHub repository. Then you will want to be able to get new changes form your GitHub repository and add them to your local repository.

Code can be changed in many ways:

User git clone [email protected]:username/HelloGithub.git

Work process

Make changes to code:

• Use the Arduino IDE to edit a sketch like HelloGithub.ino.
• Add or delete files.
• Move files to various places in the project.
• Edit files in libraries with your favorite text editor.

$ git diff

$ git diff --stat

$ git commit –a –m "Changed the files and fixed issue #1"

$ git commit HelloGithub.ino "Update HelloGithub.ino and changed blink rate for issue #1"

$git checkout HEAD∼1

$git checkout HEAD

$git checkout – filename

$git checkout HEAD∼2 filename

$git branch HelloBranch

$git checkout HelloBranch

$git checkout master

$git branch

$ git push

$ git fetch

$ git merge master

$ git pull

Workflow Summary: Creating Your Own Project

We walked through the creation of the HelloGitHub project to demonstrate GitHub’s commands, but there is a pattern in the steps we took. Follow these same steps for any project you create and you have workflow that ensures version control for one or multiple creators. Summarizing the steps we already took, we see the common steps for working on any project:

1. Create the project on GitHub.
2. Clone the project to your local machine.
3. Make changes to the code.
4. Add or remove files.
5. Commit changes to your local Git repository.
6. Push those locally committed changes to your “origin” repository on GitHub.
7. Repeat steps 2–6 as needed.

These steps allow you to work locally and keep up to date with your project.  You can use git diff, and git diff –stat or any of the many Git commands to check the difference in code version, and the changes over time for the project.

Workflow Summary: Forking Another Project

Frequently there are existing projects that you want to use, but you might want to change the configuration for your hardware, or want to add a feature to the project. Since I work with many different kinds of Arduino compatible boards, not every project is designed to work with one I’m using. For instance, between the Arduino Uno, and the Arduino Mega, the SPI pins are numbered differently.  I will typically fork the project, and then make the needed changes to my forked copy of the project. Once I’m sure the code changes are working, I can do a pull request that allows the maintainer of the main project to merge those fixes to their project.

We will use the HelloGithub project at the Pro Arduino GitHub site, https://github.com/ProArd/HelloGithub , and run through the fork process with it. Once you find the HelloGithub project, you can select fork. This copies the project into your own GitHub area. Then you will want to make a copy to your local machine by cloning it.

These are the steps for forking another project:

1. Log into http://github.com.
2. Visit http://github.com/proard/HelloFork. You will find an example of what you’ll find there in Figure 2-7.

   

   Figure 2-7. The HelloFork project you want to fork

3. Select the “Fork” option, in the list of buttons highlighted by Figure 2-8.

   

   Figure 2-8. The “Fork” button in context

4. GitHub will tell you it is forking the project, with the processing sceen in Figure 2-9.

   

   Figure 2-9. GitHub’s forking page

5. Go to your fork of the project, as in Figure 2-10.

   

   Figure 2-10. Your fork of the project

6. Clone your project with the following:

   $ git clone [email protected]:YourUsername/HelloFork.git

7. Set the official HelloFork repository as the upstream repository:

   $ cd HelloFork
   $ git remote add upstream [email protected]:proard/HelloFork.git

8. Since you just cloned it there are no changes, but once changes have been made you will want to fetch and merge changes from upstream with these commands:

   $ git fetch upstream
   $ git merge upstream/master

9. You can do a test of the merge by doing a dry run, using the following commands:

   $ git merge --no-commit --no-ff upstream/master
   $ git diff upstream/master –stat

If you want to see the difference between the changes that are being made, you can compare your code with the code on your GitHub repository with the “diff” command:

$ git diff origin/master

You can get a quick summary of the file changes by using “—stat”

$ git diff origin/master --stat

Given this list, we need to define a couple of new concepts. First, an upstream repository is typically the project that you forked into your GitHub repository. Secondly, every so often you will want to go back to the original project and pick up new files and code changes, so that you can synchronize your work with the main project. Your original project on GitHub is called “origin.” The latest version of code is called “master.” So you can compare the latest versions of “origin/master,” or “upstream/master,” with your local repository. Over time, projects can get further out of sync. If you fetch the changes from the upstream repository, you can bring the changes to your local machine without clobbering your own code, without breaking existing work by hitting it with a write over. The upstream master code will not automatically update your working area in the local master. After a fetch, you have to take specific action to merge those changes into your own project. git merge defaults to merging the fetched master with your local working master repository. The merge process will combine those changes into your local project.

Creating a Pull Request

In the section we will modify the HelloFork.ino sketch to have your Arduino username and submit the change as a pull request to the official Pro Arduino repository for the HelloFork project. At this point you will already have the forked from Pro Arduino, and cloned to your local system. So now edit the HelloFork.ino sketch to include your GitHub username. The code will look like:

/*
* Hello Fork Github Example Arduino Sketch
* Just add your GitHUb account ID and I'll add your pull request to the project.
*/
void setup() {
  Serial.begin(9600);
}
void loop() {
  Serial.println("Add your GitHub name to the code to test creating a pull request");
  Serial.println("Hello Github from:");
  Serial.println("@Ricklon");
  Serial.println("@ProArd");
  Serial.println(“@YourGitHubUsername”);
}

Once you save this code you can check the repository for the change by issuing the command:

$ git status

Result:

# On branch master
# Changes not staged for commit:
#   (use "git add <file>…" to update what will be committed)
#   (use "git checkout -- <file>…" to discard changes in working directory)
#
#        modified:   HelloFork.ino

The status result shows that you modified HelloFork.ino. This change needs to be committed to your local repository with the following command:

git commit -m "Added a new username to the HelloFork.ino sketch." HelloFork.ino
Result:
[master f6367cf] Added a new username to the HelloFork.ino sketch.
 1 file changed, 1 insertion(+)

The commit uses the “-m” to specify the message. After the message can be a list of files, paths, and or wildcards to specify the file names and directories to include in the commit. If you want to commit all changed, added, and deleted files, you can use the “-a” flag. This flag stands for “all.” The message can contain the Markdown shortcuts we described in the documentation section, like @username to mention a user and link to their account. Now that the file is committed, it is time to push the commit to your GitHub repository. That can be done be issue the command:

$ git push

Result:

Counting objects: 5, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 408 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
To [email protected]:ricklon/HelloFork.git
   4e28d3f..f6367cf  master -> master

The push result summarizes all the changes and commit information that is sent to you GitHub repository.  The “To” section. The “4e28d3f..f6367cf” in the result is shorthand for the hash that represents the commit being pushed to your GitHub repository.

Take a look at the HelloFork menu, as in Figure 2-11. Clicking on the file views the file. In our case we want to look at the commit and see what was changed as shown in Figure 2-12.

The “+” indicates the new line of code you added. A minus, “-“ represents the removal of code.

Now your project is up to date; all changes between your local repository and your GitHub repository are now synchronized.

Creating a Pull Request

Once all the changes you want to make are bundled in your repository it’s time to create a “pull request” that will move your changes to the project you forked your project from. In this case we are using your HelloFork repository. Go to the your GitHub project for HelloFork. It should appear similar to Figure 2-13.

The summary shown on Figure 2-13 shows your username, what project is selected, and where the project is from. At the same level are the project options. We are about to use the “pull request” option. You can also “Watch,” “Star,” or “Fork” the project from this menu. With “Fork” it shows you the number of forks of the project. If anyone wants to make a fork of your project, they can select “Fork.” For now just select pull request button, as in Figure 2-14.

After the pull request is selected, you are shown the “pull request” management screen as shown in Figure 2-15. Here you can decide the details of the pull request. In our case, we’re just going to ask to pull the latest changes from our project in the master branch, to the Pro Arduino master branch.

The pull request we created appears in in Figure 2-15, where we give it a title and description. Sometimes the title is descriptive enough, but there are times when you need to explain more about what you are doing, and what issues it addresses, then you can put that information in the main message area. The message area accepts Markdown, as we described in the documentation section of this chapter. Now that you’ve got your message entered, select the “Send Pull request” button shown in Figure 2-16.

Once the pull request is done, it is filed as a request with the maintainer of the project you forked from. So for most purposes, you are finished. You are just waiting for the maintainer to implement your changes, or for the maintainer to ask for more clarification. The good news is that while this process is documented in the GitHub system, the communication between you and the maintainer can be extended in email, and those emails get tracked in GitHub, too, so that nothing is lost.

How To Merge a Pull Request

Now let’s look at the flip side: What happens when you get a pull request? Once someone has submitted the pull request, you, as the maintainer, get a message and can immediately check the pull status from the pull request screen as shown in figure 2-17.

The summary of this pull request identifies who made the request, and identifies the commit that you are being asked to merge into your project. GitHub does a quick check to see if the new code can be added to the original automatically. In our case, the merge request can be automatic. Figure 2-18 shows a close up of that portion of the screen.

In this example, the maintainer selects to “merge pull request” and then is presented with confirmation and the opportunity to add a note about the merge as shown in Figure 2-19.

Once that merge is confirmed, then a summary screen is show as in Figure 2-20. The entire merge discussion is listed, so that you can review the comments. You can also review the commit status before and after the merge. If there is information about the merge that needs changing, it is possible to edit information about the merge from this screen.

Figure 2-21 shows the summary of the merge. It indicates which repositories were merged, and gives an idea of how much changed, by saying, in this case 1 commit was merged. There are times where multiple commits can be merged at once.

Figure 2-20 also shows that the merge is “closed”; this merge was identified as “#2” in the issue system. If you select “#2” you will be sent to the issue system, where you can see that the issue was closed as in Figure 2-21.

Since the HelloFork project currently has two issues, both pull requests that were completed are shown. These pull request are in the Pro Arduino project that accepted your request. In Figure 2-22 the screen from GitHub shows that two closed issues exist, and 0 open issues exist. If you made a pull request earlier to the project, then you would see them as one or more open issues. Since pull requests are integrated into the issue system, it is easy to find out who fixed issues, what issues were resolved, and where the changes came from. This leads us directly to issue management.

What is issue management?

GitHub provides an issue-tracking system. Issues include new features, problems with existing code, and code review requests. Each issue is classified in detail by this issue-tracking system. An issue can either be open or closed. It’s possible to comment on open and closed issues, as well as to reopen a closed issue.

When working with a forked project, the official issue list is maintained on the project you forked your copy from, not your forked copy.

Watching a project gives you all project updates and information. Starring a project only shows that you like the project, but doesn’t update you on every detail.

You can sort issues by the following categories:

• Everyone’s issues
• Issues assigned to you
• Issues created by you
• Issues in which you are mentioned

It’s possible to create milestones as well. These are project-specific goals that you can create and customize. You can also create your own labels that help organize the issues for your project. Example labels are:

• Priority
• Defect
• Feature
• Enhancement
• Code review
• Bug
• Duplicate
• Won’t fix
• Question

These project labels can be a quick way of prioritizing, because they visually identify the kinds of problems in the project.

Figure 2-23 shows the GitHub Issue Manager main page. In one view, you can get an idea of the “open” issues for a project. From here you can create new issues, and find issues that you have experienced. It also let’s you search not just the “open” issues, but the “closed” issues as well.

Issue management with Github

For a quick way to think about issue tracking you can follow the following process:

1. Look for the issue in the issue list as shown in Figure 2-23.
2. If it does not exist, file a new issue and include a concise subject, a description that includes a way to reproduce the problem, and, if possible, a source code example or test that fails due to the noted issue. GitHub automatically e-mails the creation of new issues to maintainers.
3. Make your modification to the project files to fix the issue and submit a pull request from GitHub.
4. Confirm the issue is fixed by testing it.
5. Lastly, close the issue in the issue system, which will update its status.

Connecting Version Control with Issue Management

The ways you change your code and files to address an issue are collected in the message portion of a commit. These commits represent progress towards adding features or resolving issues. Connecting this progress to the issue tracking system is critical because you want to know what the code changes are for and you want to make it easy to track what code fixed which issue. GitHub has added some automatic linking features that automate part of this process. If you refer to issues by “#” pound issue number like “#1” in the commit message, or the issue comment GitHub will automatically link to the corresponding issue number. Every code commit should have the issue number and description of the code changes. When the issue number is used, GitHub automatically lists the commit in the issue history. In one issue discussion, you can follow the entire set of changes to code. issue management

Commit hashes are also automatically linked. Every commit has a Secure Hash Algorithm 1 (SHA-1). This hash is not a sequential number, but a 160 bit unique string, which looks like “f9bf52794286cd2acf664f8ffd7d7547c1b4dfea,” and which is automatically linked to the commit by GitHub. This makes it easier to discuss multiple commits and peak at what was changed.

Documentation

Documentation is important. It is critical that you document what you do. When a project moves from one person who can control everything to a community of users and developers, it is important that people can find out how to use what you do, and the best way to help improve or enhance your work. It is possible to put all of your documentation into a readme file or into a documentation directory for the project, but it can be more convenient to use the GitHub wiki. Here is the quick and dirty way to use GitHub. Select the Wiki Tab on the project as shown in Figure 2-24.

[Home](wiki/Home)

```C++
/*
* Code goes here.
*/
void setup() {
}
void loop() {
}
```

/*
* Code goes here.
*/
void setup() {
}
void loop() {
}

[Link to remote site](http://github.com/proard)
[Link to remote file](https://github.com/ProArd/attinysecretknock/blob/master/ATtinySecretKnock/ATtinySecretKnock.ino)
[Link to wiki files](wiki/TestLink)

Link to remote site
Link to remote file
Link to wiki files

# H1
## H2
### H3
#### H4

Markdown:
10.  item 1
9.  item 2

Output:
    1.  item 1
    2.  item 2

* item a
+ item b
- item c

![alt text](URL to image)

![ProArduino Image](ProArduino.jpeg)