GitHub is a great tool, and while our developers use it extensively when building out websites, its usefulness is magnified when everyone on the team is using it. We don’t expect everyone here to necessarily check in and out code, but there’s a lot more to GitHub than that.
I wrote this quick guide for teams with a majority of non-developers among them. There are plenty of great guides on using GitHub for plain old writing code, but this is not one of them. If you’re a web designer or project manager who keeps hearing about GitHub, this might be for you.
What is GitHub?
Git is a version control system that helps you manage code (or any kind of plain text, really), and it’s very popular. GitHub is a hosted service that makes it much easier to not only deal with that code, but to share it, discuss it, manage issues with it, and more. Perhaps best of all, it looks good. As designers, we find GitHub “easy on the eyes,” and that’s important!
GitHub is a web-based hosting service for software development projects that use the Git revision control system. GitHub offers both paid plans for private repositories, and free accounts for open source projects. [Wikipedia]
We use private projects extensively for websites that are in development, and we also have some public projects for stuff that’s very much not proprietary. We also, however, use GitHub for a ton of features that aren’t immediately obvious.
Let’s talk about those features.
Issues
Issues in GitHub are like discussions in a project management system like Basecamp, although they wrap a ton of features into one bundle. Issues can be treated as simple checklists, or they can contain checklists within themselves.
They are formatted using Markdown, which our team knows from using many other tools. The interface for creating and editing issues looks simple, but hides a ton of features. Mentioning other folks notifies them, and automatically links to their profile. Mentioning an issue by number links to that issue. Mentioning a piece of code links to that code.
One of the most frequent thing you’ll see in Issues are graphics. We throw in screenshots of issues as they come up, which we can do from our phones or tablets while testing. Tools like skitch are great for adding notes, and we often indicate bug fixes with further visuals. To add an image, you simply drag it into the editor. Couldn’t be simpler.
All of the issues we report can be divided into two basic categories. This is similar to how you might think of a book as being a phase of writing, followed by a phase of editing.
Issue Type 1: Features
A feature is a type of issue that’s not what you generally think of as an issue, but once you frame it in that context, GitHub’s issues become a nice place to work on them. We also sometimes refer to them as “stories,” since our requirements documentation often lists out the features that a client’s website requires in terms of the stories.
Phrasing something like “Website must accept USD currency payments, and process them via the Stripe payment gateway” translates really well into a feature.
Sometimes these are very high-level, and having them in as issues is more of a placeholder for a feature to be built. Sometimes more activity takes place on a pull request (see below). But for the most part, we start off a project with a pile of these to work through.
If appropriate, a feature may be deployed to a testing or staging server, so that we (or our client) can review and play around with them. This is good for testing on devices, working through user testing, or just trying things out in a variety of circumstances or with different types of connections.
Issue Type 2: Bugs
These issues are smaller in scale, and tend to appear in the latter half of the development process.
When reporting a bug, we try to be specific. We include the steps you would take to reproduce a bug, what we expected to happen, and what actually happen. We try to be thorough enough that a developer will understand the problem, but an issue is a great place to discuss them if necessary.
Rather than being shown on a testing or staging server, bugs are typically small fixes and are demonstrated within the discussion via a screen shot or animated GIF. Sometimes, the project manager will simply show the screen shot to a client to show that the fix is in place.
Organization
There are many ways to organize these issues in GitHub. It helps to look at what each one is, and why you might use it.
Labels
We use labels on issues often, as you can filter by more than one, which is very handy.
- urgent – Use sparingly, but if you see this flag, it’s what to work on first.
- design – If help from a designer is needed, assets from a client, or very on in the process we might use this tag.
- feature – By default there’s “enhancement” but we prefer “feature”. This is one of the two primary issue types.
- bug – This is the other main issue type.
- question – If something is genuinely a question, not so much an issue, you can label it this way.
- duplicate – If you realize an issue is a duplicate, add this label, mention the correct issue, and close the duplicate issue.
- wontfix – If it is decided not to fix an issue, close and add this label.
Labels are extremely flexible, so there are often others on a project besides this. They are great for quickly organizing things in creative ways. Need a more elaborate priority system? Use a series of numbers as tags. Need to indicate research, content, or brainstorming? Tags are your friend.
They also have colors, and we know how designers love color.
Assignee
Even though you can mention other people in an issue, whoever the issue is assigned to bears sole responsibility for that issue’s next steps.
When reassigning an issue, the person to whom the issue is being assigned should be notified. There seems to be no good mechanism for being notified that you’re being assigned an issue, save for going to your issue screen and discovering it. If you mention someone, they’ll likely see a notification quickly.
You can always see who opened the issue, and if that issue is a bug, the person who created it is likely the person who should be responsible for checking and closing it.
Milestones
While they’re not as robust as many other implementations, the milestones in GitHub are a useful way of organizing issues.
You can write a description and assign a due date, as well as grouping issues within that milestone.
Pull Requests
A pull request is basically an issue that relates specifically to a proposed set of changes to the code, and has many handy features for discussing that code.
Being able to add notes relating to specific lines of code lets us help developers solve problems if we happen to know what changes are related to the problem. Another developer can even propose a set of code changes, right within the discussion.
For proposed design changes or things that need to be tested, pull requests have a handy workflow. Since a pull request corresponds to a proposed “branch” of code, that code can be placed on a testing server. That way, everyone involved can try it on all their devices, and feedback from testing can happen alongside the code.
Pull requests tend to be used for larger features. For small-scale bug fixes, discussing and closing an issue is generally sufficient.
Company Notebook
Oh, and by the way, we keep our entire company “handbook” in a git repository in GitHub.
This doesn’t mean the whole team needs to understand how to work with a git repository. GitHub provides an excellent web-based interface for adding, modifying, and searching documents.
This is an incredibly simple yet robust way of handling documents like our company handbooks, records of all our clients logins and passwords, and other secure and valuable information.
The fact that everything is in version control, and happens to be backed up on any number of our computers, is just a bonus.
Shortcomings
GitHub isn’t perfect, and there may be any number of deal-breakers in here for you.
- File handling kind of sucks for non-programmers. You can embed images in discussions… but no other types of content. You can upload arbitrary files to “release tags” in your code… but not in discussion about said code.
- You can’t see all issues assigned to a particular person (besides yourself) across all projects. Kind of makes project management a challenge. (While it’s true that on a single project it’s possible to see another person’s assigned issues, if you have a lot of projects this isn’t a great solution.)
- You can’t discuss a file by itself. You can hunt down a change and comment on that, but it’s certainly not the same thing. The closest you can come is creating an issue that prominently links to the file you want to talk about.
- There’s no reasonable way to expect most clients will use the tool. It’s hard enough to get your own team to use it.
Conclusion
As you can see, there are a lot of drawbacks and workarounds here. Is GitHub our sole tool for project management? Unfortunately, no. But it’s great if everyone in our team can participate in it, because its strengths are often worth it.
If you already use version control as a part of your development process, getting the rest of the team involved is worthwhile.
If you don’t? You can’t be serious. Start using version control today!
