In my last post, I introduced a set of features (and failings) that might have you wondering if Github can grow with your team. In this post, I’m talking about tasks, workflow and keeping things moving.

Github’s Workflow Is Simple And Cool

When you’re starting out, Github’s approach is really helpful. You can create a task with just a summary sentence. If you want, you can add a more detailed description and some labels.

Tasks are open or they’re closed, and you can close a task with a commit. From a developer’s perspective, it’s wonderful to grab a task and write some code, then update the task without having to visit the website. You get to stay in your IDE, your command-line — whatever tools you’re using to do the work.

The Real World Gets Complicated

These features work very well for teams that are just starting out, and for projects that may have somewhat disconnected participants (e.g., open-source projects). But as your team begins to deal with marketing, sales, customers, or even other dev teams, you may rub up against some important limitations.

There’s more to life(cycle) than Open and Closed

Very often, there are other pieces to your workflow than just coding. There could be planning, design, code review, testing, deployment, and other activities. It’s pretty common to reflect some of that workflow in the status, so that everyone can tell where a task is and what needs to be done next, without having to re-read then entire history.

Closing a task just because you’ve committed some code assumes that everything else will go right. Usually, committing code is the beginning of the process, not the end.

Not everything fits in the same box

Not everything is a task to be done in the code. Sometimes, you want a place to flesh out a user story, or discuss the design for a specific page. Maybe you need to track servers, or which customers have which version of your product.

You might be able to jam these different kinds of information into a Github task, but it ends up being a bigger version of the labeling problem from my previous posting.

What’s going on

Github has some pretty decent release/milestone tools, and you can group tasks into a milestone to track overall completion. That project-level view can be great, but what about planning and tracking your current sprint Or planning and tracking your own day

Standups get a lot easier when you can automatically see what the team worked on recently, and when the team can identify what they plan to work on.

What’s really important

This is one that everyone runs up against pretty quickly. Putting a priority on each task allows the team to keep moving, by knowing which tasks to work next. Without prioritization, everyone’s just guessing about what is most important.

Github has no way to prioritize tasks. Even if you use a label (to beat a dead horse), you won’t be able to sort them.

Plans get tangled up

It’s pretty easy to enter and manage tasks in Github, and depending on your level of detail one task might be completely stand-alone from another. Almost inevitably, though, a task will be blocked, waiting for some other task to finish. Your new web page needs an API update from someone else. A customer’s support ticket might be waiting on a bug that someone is working on. Or a use case can’t be complete until all three web pages are working together.

The ability to manage dependencies has been asked and discussed many times over the years, and Github just doesn’t want to take on the complexity. It doesn’t have to be a Gantt chart, but making sure that everyone knows when tasks are blocked (and when they become unblocked) is key to maintaining project momentum.

A More Realistic Approach

First off, don’t expect Github to change. The simplicity of their task management is perfectly suited for many, MANY projects. It’s easy to get started with, and is a great place for sharing open-source and personal projects.

But maybe your team has started to suffer from that simplicity, and you’re looking for something to fill in the gaps that Github leaves. You might even be tempted to try one of the dozens of “bolt-on” tools that claim to integrate tightly with Github.

Instead, let me suggest that what you really need is something that was built from the ground up to start simple, grow to be comprehensive, and stay elegant. Something that’s easy to use, but allows more complexity as you grow into it.

Here are a few more simple pieces of advice:

• Instead of shying away from adding different status values, be honest about the workflow you want and make the tool serve your needs.
• Consider that maybe you need a different set of fields for tracking use cases or UI designs, versus coding tasks, versus customer support.
• Don’t settle for something that’s too simplistic, or a patchwork of loosely-coupled tools, when working around their limitations will cost you time that’s better spent on your actual mission.

If your tools are preventing you from improving your process, maybe it’s time to improve your tools.

Come back soon for another sign that you might have outgrown Github .

Come try GForge Next for simple, comprehensive and elegant collaboration.

Github is WONDERFUL. I have used it for a long time now, and it’s great. It’s easy to get started, and especially for one-person projects, it really helps keep things organized.

But as you start to add team members, competing priorities, and overall complexity, something changes. In lots of little ways, Github starts to show that it just wasn’t designed for long-haul software projects, with many team members and a non-trivial workflow.

Here are some of the things you might already be dealing with:

• You’ve created so many labels that you’ve written a wiki page to tell everyone how to use them (and how NOT to use them!)
• Maybe you want to keep track of bugs and support tickets separately.
• Perhaps you don’t think that developers should be able to close a ticket just by committing code.
• Maybe you’re tired of having to search in Google Docs, Basecamp, Slack and Github to find where you talked about that new feature.
• Could be that you need to manage the relationships between tasks that depend on or block each other.

I’ll do a blog post for each of these topics. This week, let’s start with the first one — labels.

Labels

Labels are quick and easy to use, offer a lot of flexibility and require virtually no setup or configuration overhead. The default labels in Github look something like this:

Those are probably fine for 98% of new Github projects. Over time, however, most teams will expand on the list of tags to include different values than the default list, and even different types of data. Adding categories for basics like type, priority, and status makes a lot of sense when you’re managing a backlog. But all of those new values expands the list beyond what you can keep straight in your head.

So, how can teams use complex label sets reliably One common convention is to use a prefix word to identify the group to which each label belongs (courtesy of Dave Lunny):

This approach has the benefit of including the type of label as part of the label text, so you won’t be confused between “Status: Test”, “Environment: Test”, and “Task Type: Test”. Visually, the various colors can be used to show differences in the specific values, like production vs non-production, or high priority vs lower priority.

The downside is that when viewed across label types, the different colors are confusing and even downright jarring. Instead of quick visual signals based on color, you actually have to read each label value. It’s bad enough when looking at a single task, but when browsing a list of tasks, it can be a hot mess.

Another approach is to use similar colors for grouping. Here’s an example (from robinpowered.com):

While it’s much easier on the eyes, you no longer have the label type included with the label value. Also, this particular set of labels combines and separates a lot of values in ways you won’t appreciate later — for example, why is the production label in “Problems” and not “Environment” There’s likely information on a wiki page somewhere, explaining that you don’t choose anything from “Environment” when it’s a production issue, right

This next example isn’t really an example at all, but a cautionary tale. Imagine walking into your first day with these guys:

This isn’t someone’s drug-addled fantasty project, either — it’s servo, a very active and popular project on Github.

Tools For Your Tools

In response to this widespread need, there are actually tools (like git-labelmaker) dedicated to helping Github users automate the creation and management of complex sets of labels, using different naming conventions, color schemes and labeling styles. Which is very cool — except that it seems like an awful lot of work to go through, doesn’t it If someone has created a tool to help you use another tool, maybe it’s the wrong tool.

Tag/label functionality was never designed for complex values or workflow.

A Right-Sized Solution

Instead of a mashup of various labels, organized by a prefix word or a color scheme, consider this layout (with a few additions that are, IMO, obvious):

Separating these various concerns also allows you the flexibility to require some fields when a task is created, and wait for the right step in your workflow for others. Instead of manually enforcing your task management process, you can allow your tool to do it for you.

One last benefit — if you’re using separate fields instead of specific tag values, then changing the name of the field or the values over time won’t break old data. The new field name or value(s) will be reflected in older tasks automatically.

If your tools are preventing you from improving your process, maybe it’s time to improve your tools.

Come back soon for another sign that you might have outgrown Github — next time, we’ll talk about Github’s one-dimensional task tracking.

Come try GForge Next for simple, comprehensive and elegant collaboration.

In my last post, I talked about some criteria for choosing between all-in-one or best-in-breed tools. Now, I’ll apply those criteria to our product space, and try to show why a unified team collaboration tool makes more sense than what you might be living with now.

So, let’s imagine that you’re looking to solve the following problem: How can we get everyone rowing in the same direction

By “everyone,” we mean executives, product owner(s), designers, development staff, customer service, maybe even customers themselves.

And by “rowing,” we’re talking about all of the things it takes to get your product to the customer — things like planning, design, coding, marketing, testing and support.

The Accidental Integrator

The worst-case scenario is also the most common — each discipline area adopts whatever tools appeal to them.

NB: This is a simplified version of actual events from a previous job. The details have not been exaggerated, and the people involved were otherwise very capable, smart, and successful.

• The Product Owners all decide to use Trello, and thus force it on the development staff.
• The designers prefer Basecamp, where they can organize screenshots for the various user stories they’re working on. This means that the Product Owner has to look there as well, and so do the developers, and possibly also the customers.
• The developers decide on Github, since it’s easy to start and Git is pretty awesome.
• Customer Support starts a wiki, so they can get all of their procedures and help scripts in one place.
• They already use FogBugz for tracking customer issues, and neither Trello nor Github has the features they need. This means that the Product Owner and developers have to look in FogBugz almost every day, as they respond to problems reported by customers.
• The executive staff needs all of the above to keep a handle on what’s happening where. They also create and manage a couple of spreadsheets in Google Drive, to keep summary data for the various projects that are in process, and to prioritize upcoming work.

Here’s what that set of tools ends up looking like:

Of course, some of these tools can be tied together with vendor-supplied integrations, web hooks, or some simple scripting. Adding these integration points might make things more convenient for users, but it doesn’t change the overall picture:

Inevitably, some amount of developer time each month (or week) will now be spent troubleshooting why x is no longer taking to y, and fixing it. People also regularly forget which password goes to which system, and need resets on a recurring basis. [Ed. This happens to me ALL THE TIME.]

Regardless of how good those integrations are, everyone still has to search across two or three or more tools to find what they’re looking for.

Each tool you add is another silo of data and process, and more friction in the overall workflow.

A (Kinda) Integrated Solution

Many teams opt for the Atlassian/Microsoft/IBM approach — buying a set of tools from the same company, with the promise of tighter integration. It’s sold as an all-in-one solution, in as much as you’re buying from one vendor. And for the most part, that’s true — until it’s not.

Tool suites like these do a much better job at tying related data together — build status can show up in the related tasks, support tickets can reference wiki pages, chat can become your company’s heartbeat. All of those capabilities help to decrease friction, distribute knowledge, and keep the entire organization plugged in to the right priorities.

But they’re still separate tools. You still have to flip from one app to another to search, get the details, or make updates. Each tool is still deployed and managed in separate software versions, which (sometimes) fall out of compatibility with each other. And don’t forget that you’re still going to pay licensing and maintenance for each tool. Even at a bundled rate, you’re probably getting soaked.

Half-way integrated is better than the patchwork quilt approach, but it still creates implicit silos of data, and introduces other hidden costs. It’s like being half-way delicious.

The Whole Enchilada

Speaking of delicious, what happens when you *actually* integrate tasks, wiki, chat, releases, documents, source code, support, and continuous delivery If you could get all of these chunks of functionality in a single system, how would it affect your experience and productivity

There are some big benefits:

• A seamless experience for managers, development staff, creatives, support and even customers to get involved in.
• A single source of truth for what’s important, what’s done, and what’s next.
• One place for your institutional knowledge to live on. On-boarding becomes easy. Hard-won company wisdom doesn’t disappear when someone leaves or changes roles.
• One search box that is deeply connected to all of your projects, source code, documents, information, tasks and discussions. Find a specific key word or error code no matter where it’s hiding.

There are lots of situations where best-of-breed thinking makes sense. In areas where a specific tool improves your productivity, saves money, or just makes work more fun, it can be worth it. If the need you’re filling isn’t central to your business, then it’s not a huge risk to try (and maybe abandon) something new. But that’s not what we’re talking about here.

The way your team organizes and works together is possibly the most important and valuable part of your entire business. Trying to run things using a patchwork quilt of point solutions might seem cool at first, but it’s probably not where you want your team spending their time.

That’s why we built GForge. Because we do what you do every day, and we think it should be easier.

Come try GForge Next, and let us know what you think.

Note: My editor wanted me to include email as part of this discussion, but it added way too much to the article. GForge does some great things with email, and I will publish something soon to show how and why.

A quick run-down of the skills we’re looking for, and how we’ll put you to use.

Come and join a world-class company that supports thousands of project teams around the world. We’re looking for folks to fill one or both of two categories:

• First, customer service handling technical issues with customers – sysadmin stuff, configuration, tracking down log entries, etc.
• Second, help with building new features and testing GForge Next.
  

What we’re looking for:

1. Work from home 12-20 hours per week, Monday through Friday. Specific start and end dates are very flexible.
2. We’re pretty flexible on schedule, as long as the results are right.
3. For support duties: A moderate amount of knowledge in Linux/Web systems administration. Stuff like:
   • Linux basics (ps, grep/find, sed/awk, top, iostat, etc.)
   • Package mgmt (e.g., yum, apt-get, rpm, etc.)
   • Scripting (bash, php)
   • Apache httpd setup and config (conf files, modules, etc)
   • Version control tools like CVS, SVN, Git.
   • Bonus points for SQL and Postgres!
4. For GForge Next development duties:
   • Programming experience in PHP (or Python)
   • SQL basics (bonus points for Postgres)
   • Familiarity with HTML5 and CSS
   • Some Javascript programming experience
   • Extra bonus points for Angular 1.x experience.
5. Great customer service attitude. Especially when they might have done it to themselves.
6. Last and most important: willingness to learn a lot of cool stuff, and share what you know every day.

Responsibilities of the Job:

1. Make customers really happy by fixing their problems.
2. Research issues that don’t have an easy answer.
3. Willingness to dig into code to possibly give a better bug report to our engineering team. Maybe even dig in and fix the bug yourself.
4. Work from wherever you like, but be productive and respond quickly during working hours.
5. Lean on other GForge staff and share knowledge whenever possible.
6. Stay in the loop – email is a given. We also camp out together in chat all day and have an informal daily standup, usually on Google Hangouts.
7. Document solutions that can be re-used.
8. Depending on how busy things are, we may even ask you to help test out new features and bug fixtures.

GForgeNext is the newest incarnation of our long-lived project collaboration tool. It ties together all of the most important features that teams need to deliver big things – like task tracking, team chat and integrated source control. And in the next several months, we’ll add a lot more.

Next employs a Single Page Application (SPA) front end, and relies on our public REST API for all of its functionality. Everyone can now build great tools and integration points with GForge using the same REST API that we do.

On that topic, then, let’s explore the API and build an example or two.

REST Basics

There are plenty of good, detailed tutorials about REST. Here are the basics you need to get started with ours:

• REST deals in resources. In our case, things like users and projects.
• REST uses the HTTP verbs you already know to get things done. GET, POST, PUT and DELETE are the most common.
• REST also uses the same HTTP response codes that web pages use. 404 That record doesn’t exist. 400 You submitted something invalid. 500 You broke it.
• REST uses the normal query string and request body that HTML pages use.
• Data is typically exchanged (submitted and returned) in JSON format, which is easy to handle on most platforms.
• Our REST API also accepts regular FORM POST format, so it can be called even from static HTML pages or libcurl.
• All of the resources, methods and parameters for the API are documented in our API Docs.

Logging In

GForge has very deep and flexible access controls, and the data you receive from the API will usually depend on the user requesting it. You can submit a separate user ID and password with each request, or get a session ID (from the /usersession endpoint).

Using curl:

[code language=”bash”]
curl -X POST https://USERNAME:PASSWORD@next.gforge.com/api/usersession
[/code]

Results in:

[code language=”javascript”]
<pre>{
"SessionHash":"e3403h9ldbssr2…o781jne2"
}
[/code]

The POST verb is used to create data on the server – in this case, a new session ID is created if the user and password match up. You can then use the session ID in place of the password for further requests. In a browser, the session ID will also be set in a cookie just like visiting the login page on a web site.

To “log out” and remove this session:

[code language=”bash”]
curl -X DELETE https://USERNAME:SESSION@next.gforge.com/api/usersession/SESSION
[/code]

Result:

[code language=”javascript”]
{"result":"success"}
[/code]

Note that you have to include the session ID for both the authentication and to specify which session to delete.

Get Some Data

Now that we have an authenticated user, we can use it to get data from the API. How about the user profile for a friend

Request:

[code language=”bash”]

curl https://myuser:e3403…jne2@next.gforge.com/api/user/my_friend

[/code]

Result:

[code language=”javascript”]

{"id":99999,"unixName":"my_friend","password":null,"firstName":"My","lastName":"Friend",
"email":"my_friend@email.tld","status":1,"externalId":null,"isGroup":"N",
"ccode":"US","language":"en ",
"img_url":"/images/custom_avatars/99999.jpg",
"details_url":"/api/user/my_friend/details","api_url":"/api/user/my_friend"}

[/code]

What’s Next

Read the API docs, and see what you can get under the /api/user and /api/project endpoints. There are a whole bunch of sub-entities within each one. Then maybe move on to /api/tracker or even /api/trackeritem to see tasks.

For the especially brave, try /api/poll…

Got questions Comments Bugs Leave a comment, or find me on Twitter @mtutty.