by Jerad Bitner on June 20, 2012 // Short URL

Managing Projects with GitHub

We've tried a lot of project management systems over the years. In some way, they have always seemed lacking, confusing or just a pain in the rear end. If they had good tools for project managers, they were confusing to developers. If they were useful for developers, designers complained about the eye-sores. No one system ever seemed to satisfy the team.

We recently started using GitHub for project management after the developers started raving about how much they loved it for managing code. To our surprise, GitHub has proven a solid option for project management. Our designers have even started using it for some of their projects, which I think says something about GitHub's aesthetics. With a little bit of something for each role, GitHub is starting to come out on top as the tool of choice for hosting code, managing projects, and facilitating project communication.

Project Introductions

GitHub is pretty developer-centric. As such, the first thing a developer sees when they open a project, is a view of the code repository. Below that, GitHub automatically renders the README file found in the root of the code base. It's a very typical practice for software projects, especially open source software projects, to have this file in place. The README can be in various formats, but a favorite of mine is Markdown. Simply giving the README an extension of .md tells GitHub to render your README.md using the Markdown syntax. Even better, GitHub has it's own flavor of markdown. Since the developers of your project see the README first, this is a great place for information that will get them up and running with the project as quickly as possible. Be concise. If you need to write more than a few sentences, chances are, you should be linking off to more in-depth documentation in your project's wiki. Here's a quick guideline of some of the things that you might want to include in your README.

  1. A quick project overview.

    Provide a short description of the project's goals and a bit of background. Any links that you frequently access are also good to include up at the top as well, for easy access. Everyone loves easy access.

  2. Information about the directory structure.

    Typically we have more than just Drupal in our repository root, so it's helpful to have a brief description of what is in there. We typically have a drush folder for aliases and commands, as well as a patches directory with its own README.

  3. How to get started developing.

    Tell the developers what the best way to jump into the project might be. Things like, "clone this repository, create a feature branch, run the installer, download a copy of the database, etc.. Whomever reviews the pull request should also do things like remove the remote branch from the repository once it is merged."

  4. Code promotion workflow.

    It's a good idea to outline your development process, as it may change from project to project. Do you want people to fork your repository and send pull requests; create feature branches and send pull requests; or just go ahead and commit to master? Let the developers know up-front, so there's no confusion.

  5. Environments.

    Outline information for your dev, staging and live environments, if you have them. Also, outline the process for getting things to the various places. How do I make sure my code is on staging? What is the best way to grab a database dump? We like to setup drush aliases for each environment ahead of time as a means of outlining this information and giving developers a good starting point. This document contains some example commands for doing some typical operations. Here's an example.

  6. Links to where to find more information.

    Typically this is our wiki, where we keep more detailed documentation and notes on things; project details like the original proposal's SOW, credentials to environments, Scrum Notes, Pre-launch checklists, etc.

We've attempted to create a drupal-boilerplate, of sorts, for our Drupal projects which we're continuously re-using for new projects and modifying when we find things that work better. Take a look, and if you find it useful, please feel free to use it! If you find anything missing, or have ideas on improving it, please fork it and send us a pull request!

Working with GitHub Issues

GitHub has a pretty simple issue management system for bug tracking, but it is flexible enough to be a pretty powerful tool for managing entire projects, large and small. It has issues which can reference each-other; labels for attaching meta data to your issues; methods for attaching code to your issues; and even milestones for grouping and focusing your issues within time blocks.

Referencing and Association

Issues can be associated with each other by simply throwing an #issue-number (ex: #3) within the body of another issue. This is useful in many ways. Firstly, it keeps the relationship simple. We don't have to worry about what kind of relationship it is (parent/sibling/child), just that it's related. Nevertheless, there are a couple of tricks that make this a little more useful if you understand how it works. Let me give you an example.

Let's say you typically create an issue for a content type, and one of the fields on that content type is a taxonomy vocabulary. You probably want to break that vocabulary creation out into it's own issue. So you create the issue for the news content type news-content-type

and then you create an issue for the taxonomy vocabulary and, within your description, link to the news issue. tags-taxonomy

Just by putting in the #ticket-number (in this case #4) GitHub creates a link to the news issue AND it places a back-link reference within the news issue to your tags issue! news-tags

As a part of this reference you will notice that it also gives you the status of the referenced issue. Very handy for whomever is assigned this news issue. They can easily see the status of it's 'dependency'. I use that term loosely because it is a dependency in this instance, but not always.

Issue Labels

Tags are a simple and effective way to add metadata to your issues. A lot of systems tend to create fields and categories with various values in an effort to allow you finite control of the metadata for an issue. I've found the simple tagging system that GitHub employs to be very efficient and more flexible.

GitHub comes with a few labels by default: bug, duplicate, enhancement, invalid, question, and won't fix. These give you a good idea of how to start using labels. For example, "bug" is a type of issue, while "won't fix" is more of a status. Tags can be anything, and if chosen wisely, can give any developer an immediate clue as to what sort of ticket it is, what section it might apply to, or what status it is in at a quick glance.

While they're useful for developers, they're also good for the organizer of the project in that they serve as a great filtering mechanism as well. For instance, just by selecting various labels, I can see all of the issues that are "migration" issues for "taxonomy", or "content types." content-migration

Attach Code to an Existing Issue

Pull requests are an amazing tool for code collaboration. If you're new to the concept, check out this pull request demo. It's a quick and easy way for developers to basically create a copy of the code base (by either forking or branching) and suggest modifications to the existing code, or contribute new code. It allows the other members of the project to then review that code, make their own suggestions with in-line commenting, and then make a decision as to whether to merge it into the main code base or not. We've found the in-line commenting with pull requests to be immensely useful since they keep everyone in the project in the loop with changes that are happening. code-comments

Pull requests in general are a great means of peer review and have helped to keep the quality of our code up to everyone's standards. There's a bit of overhead in that it may take a little longer for some new piece of code to be merged in, so plan accordingly. But this also means we find bugs sooner, typically before they're actually introduced into the master branch of the code.

I had one gripe with pull requests: when you create one through GitHub's web interface, it basically creates a new issue. Though you can certainly reference a particular issue within your pull request, it's still a separate issue. However, through a nice command-line tool called Hub, we've found there's a way to turn issues into pull requests! Very handy for keeping your discussions and code all in one place and not having to deal with multiple issues about the same thing.

Milestones

GitHub has a mechanism for milestones that is actually quite typical of many project systems these days. When you create a new milestone, it simply has a title, description, and a date choosing mechanism. milestone

You can have a nice overview during the time-boxed iteration that gives you the percentage complete. closed

We tend to only plan one sprint ahead, but there is a milestone created for each iteration up until the end of the project. open

We grab these tickets from the Backlog, which is essentially just any ticket that is not in a Sprint. backlog

Huboard

GitHub's issue tracking system lacks a mechanism for prioritizing your issues. You could probably come up with labels for High, Medium and Low priorities, but I tend to prefer an ordered list with the highest priority things on top.

Enter Huboard, which gives you a nice Kanban-style interface (similar to Trello) right on top of the GitHub api. You're looking at your GitHub issues, but with a different interface. The instructions for setting this up are quite sufficient, so I'll not re-iterate those, but I've found that it's quite easy and quick to setup on Heroku with very little maintenance overhead. With Huboard, we now have a means of seeing what the priority tasks are for the week and it gives developers an easy way to see what they should work on next. huboard

Logins

Some project management systems require a new login for every instance of the software. For instance, if you have two different clients using the same project management software you may have to remember two different username and password combinations and your authentication will not transfer from one to the other. Github allows users to access all the projects and repositories you have permission to without multiple authentication.


Github is lean and spare, and you may find there are features missing that you're accustomed to. Luckily, the team over at GitHub is continually making improvements to their product and they blog about it often.

In summary, GitHub is great for the technically-minded person, but less tech-savvy people may not find it as attractive. I'm still working on ways to report on progress to project stakeholders in a more visual way and when I find one I like, I plan to update you all.

If you have any suggestions on things we might also do to improve our process, or would like to share with us some of the exciting things you're doing with your own processes, please hit us up in the comments section! We'd love to hear from you! And remember, Lullabot loves you!

Read this article on GitHub.
Fork me on GitHub

Jerad Bitner

Sr. Technical Project Manager

Want Jerad Bitner to speak at your event? Contact us with the details and we’ll be in touch soon.

Comments

sirkitree

not native

GitHub doesn't natively have a mechanism for time logging that I know of, though with integration into *many* other services, I've seen this possible.

You can see a list of all that GitHub integrates with if you go to any of your project's Admin area and click on the 'Service Hooks' tab..

Reply

sirkitree

We still use Unfuddle for

We still use Unfuddle for some of our existing projects, but we're doing some of our new projects in GitHub.

I won't use this as a means of complaining about Unfuddle; it's served it's purpose quite well. We've had some pain points with it though.

I think the main reason for the initial move has to do with the fact that some of us use GitHub personally quite a lot, and end up finding lots of other useful projects there. And if you're using one system all the time, it's nice to not have to switch into others.

Reply

Mark

Great!

This is awesome. I love the Huboard interface especially.

Could you explain how this article is hosted on Github and what the advantages are in the editorial workflow, as opposed to editing in Drupal?

Reply

sirkitree

Experiment

It's where I was working on it and was kind of an experiment in collaborative document writing. I was also planning on trying to illustrate some of the points in this article in the GitHub issue tracker associated with the article's repo, but failed to put the time into it.

However, I did get some pull requests before publishing it here (which you can see on GitHub).

One major pain point with that though, was that I originally wrote it without line breaks, and pull requests against that were very hard to read since Git has line by line change control and diffs where super hard to read with really long lines.

So I then manually converted each long line to separate lines at about 80 characters. However, making each line it's own also had it's pain points. While you can read a diff much easier, it's not really intuitive to write and edit on separate lines in most editors.

If there is an editor out there that automatically takes care of actually keeping things to a certain line length without just wrapping (actually manages hard returns) that might be a way to solve this problem. If it could be solved, I would certainly recommend a workflow like this for collaborative document writing.

Reply

Kimadactyl

Databases?

Can you comment at all how you manage databases using git? It's the stumbling block that always feels messy when using a CRM in version control software :)

Reply

sirkitree

Never

I'm of the opinion that a database dump never belongs in version control. It should be distributed by other means.

We typically get a database onto a staging server and then developers can use drush to grab the database, using `drush sql sync`.

This goes for user uploaded files stored in the site's `files` directory as well. We use `drush rsync` to grab these any given environment and do not commit these to version control either.

Committing a database dump has security implications (if the wrong person gets ahold of your code repository, then they also have access to your website's users. It's also a file that can get quite large and isn't always a necessary thing to download just to take a look at the code. One could say the same about the files directory.

Reply

David King

What about syncing the database up to the staging server?

Syncing the database from a single server down to multiple distributed development servers is relatively easy with drush. But the difficulty remains in syncing the distributed development databases up to one server (test, qa, staging, etc.) I've seen and heard of a few different approaches.

1. Features (not the panacea some people make it out to be)
2. Liquibase (versioned table structure or just config management data?)
3. Versioning database dumps (bad for all the reasons you mention above and more)
4. D8's Configuration Management Initiative (this can't come soon enough)

So how do you handle merging the distributed databases back into a single server?

Reply

sirkitree

Don't

Typically we do not do this at all. Any database updates we handle in update hooks. This ensures that database schema changes or insertions are handled in code and can be controlled just like the rest of the code.

From the start of a project, we maintain an install profile that get's the basic site setup. This helps to keep everyone's environment in sync because they can simply reset it by reinstalling from the install profile.

This isn't always maintainable once you have a site already launched and user content being input. In those cases, we push code updates that contain these update hooks in either the appropriate feature, or a site module's install file that make the required database changes.

Reply

Victor Kane

We've been using GitHub for PM for a year now

Check out our article http://awebfactory.com/node/474 and see this sample https://github.com/victorkane/lit/issues?direction=desc&sort=created&sta...

Once GitHub rolled out milestones and issue tags, and the references started working, we began to love it.

So happy to see your article, thought we were the only ones :)

Our beefs:

* Make issues a repo like the wiki (you can download with the API, but there's something nice about being able to grab a backup easily and consistently of what amounts to a good part of a project's documentation).
* Make it easier to reference even more stuff

We do use Pivotal Tracker, though, on projects involving large teams. http://www.pivotaltracker.com/

Victor Kane
AWebFactory

Reply

sirkitree

Thanks!

Saw your article while I was researching mine. Thanks for the link!

Yes, backups of the issues would be amazing! :)

And I'd love for them to do automatic linking to issues from the wiki. Sometimes we use the wiki for large requirements and it would just make it that much easier to have something like [#13] in the wiki to link off to issues. Also, when an issue is closed, cross it out automatically.

Huboard has actually been more maintenance than I wanted, so I'm going to check out Pivotal Tracker. Thanks for the heads-up!

Reply

Dwight Aspinwall

Story estimation

Thanks for the great intro. We've been using Pivotal Tracker for about three years and really like it, although we're always on the lookout for alternative tools. One question, I saw no mention of story estimation in your write-up. Is this supported by GitHub? Along with prioritization, this is a key element of agile dev (and one that Pivotal does very well).

Reply

Shane

Thanks for the quick response

Thanks for the quick response Jerad. I'm not a git expert by any means but we use are currently using Beanstalk as our remote repo. Basically we work locally and then commit /push using Tower (nice Mac app). Beanstalk then allows us to setup deployments so it is easy to deploy code changes to a web server. I'm researching to see if github offers the same thing.

Reply