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 to necessarily check in and out code, but there's a lot more to GitHub than that.
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.
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.
Every issue 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.
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.
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).
These issues are smaller in scale, and tend to appear in the latter half of the development process.
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.
There are many ways to organize issues in GitHub.
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.
- 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.
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 mechnism for being notified that you're being assigned an issue.
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.
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.
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.
While it has the basics covered, GitHub can be at a disadvantage when it comes to staying in the loop on your projects.
Another disadvantage that we've struggled with is the inability to see all issues assigned to a particular person. 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.
We have started using Slack, and it shows activity on issues and code in GitHub within specific chat rooms pretty well.
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.
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.
- As mentioned earlier, you can't see all issues assigned to a particular person (besides yourself) across all projects. Kind of makes project management a challenge.
- 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.
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.