Hardware Reference
In-Depth Information
can then be tracked from when a new issue is reported to when the issue is closed. Even more importantly, the code
changes related to the issue need to be collected together. Every code commit should have a message describing the
collection of changes. This way there is accountability for who made the changes and when the changes were made,
and you will have a good chance of figuring out why the changes were made the way they were. In order to ensure
that the code and issue are hyperlinked together, many users write something like, “This was fixed by
#issue_number
.”
The good news with GitHub is that every code commit can be connected to the issue it resolves.
When working with issues it is typical to take the following steps.
1.
Look for the issue in the issue list.
2.
If it does not exist, file a new issue, including 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. Then the issue number is generated.
3.
People watching and maintaining the project will get an automatic e-mail when you
generate your issue. If you need to discuss the issue, you can send an e-mail to the develop
list with the issue number and a hyperlink to the issue.
4.
Someone may claim an issue, or you can assign it to a programmer, and that connection
between issue and programmer can be seen in the issue list. If not claimed, you can
update the code yourself to address the issue, and then create an official request that your
code fix be added to the main project. This request is officially called a “pull request.”
5.
Once the issue is confirmed fixed, the issue can be marked “closed” using either the
commit, pull request, or issue manager interface.
6.
If for some reason the issue is not truly resolved, you can reopen it.
This pattern helps everyone coordinate their work strategies, and divide up the effort of fixing project issues as
well as project feature goals.
Documentation
Project documentation is the identity of your wiki project. It is where code experts, and people who are not source
code experts and only want to use the project, go to find out what your project is about. It is like a Wikipedia
entry for your project. In fact, the type of documentation we will be looking at is wiki documentation. We will use
GitHub's wiki documentation to provide a statement of purpose; a description of assembly; a link to step-by-step
images of the project; and a link to the schematics, Eagle, or Fritzing files to the printed circuit boards. Sometimes
people check only the wiki documentation and never see the source.
The GitHub wiki uses what is called
Markdown
formatting in order to display the text of the pages. The details
of Markdown syntax are found at
https://help.github.com/articles/github-flavored-markdown
.
These pages
can be edited online in the wiki interface. Additionally, other people can use the wiki and help you keep information
about your project up to date.
Project Management for Social Coding
In this section, I describe one way to set up your development environment using the version control system Git and
the online code-sharing repository GitHub. Git is the distributed version control software that GitHub uses as a basis
for their social code management website.
