Help Docs

When you push updates to a remote Github repository, you can automatically update the tasks associated to a DoneDone project by using a simple syntax in your commit or pull request messages. With this simple syntax, you can...

• Add a comment to a task
• Reassign or unassign a task
• Update the status of a task

This will also work for Mailboxes and Conversations in exactly the same way, but we'll just use "Projects" and "Tasks" in the documentation going forward.

Message Syntax

A message will modify a DoneDone task if it contains specific information inside a set of square brackets that begins with the task number in the following format:

[dd#XXX ..... ] Rest of your commit message...

Here's an example. The commit message below would add a comment, update the assignee, and change the status of a DoneDone task when pushed to the remote repository.

[dd#248 kawai.cheung@donedone.com in progress] Began fixing browser issue.

• The comment "Began fixing browser issue" will be added from the author of this commit to #248.
• The status will be updated to "In Progress". DoneDone will omit spaces when checking for a status name match. In other words, in progress would be equally as valid as in progress.
• The task will be re-assigned to the user with email address kawai.cheung@donedone.com.

If you're making a commit within Github itself or within any Github software that splits up the message into a "title" and "body" format, note that the message ultimately concatenates the "title" and "body" (separated by a break return). So, the commit message above can be split up between the "title" and "body" however you wish, like below:

Syntax Examples

Of course, you don't have to do all three things with every commit message. If you just want to do only a subset of actions, it's simply a matter of adding the appropriate syntax to the commit message. Examples:

Add a comment, re-assign, and update the status of #3

[dd#3 jane@acme.com closed] My comment or [dd#3 closed jane@acme.com] My Comment

Note: It doesn't matter if the assignee or status is specified first.

Only add a comment to task #15

[dd#15] Fixed first part of this bug

Only change the assignee of task #12

[dd#12 john@acme.com]

Only change the status of task #362 to "Ready for Retest"

[dd#362 ready for retest]

Only unassign task #17

[dd#17 unassign] or [dd#17 unassigned]

Add a comment, re-assign, and update the status to "In Progress" of #248, #255, and #271

[dd#248 dd#255 dd#271 john@acme.com in progress] Fixing similar tasks

Only add a comment to #248, #255, and #271

[dd#248 dd#255 dd#271] Fixing similar tasks

Hopefully this is beginning to make sense! 😀. A couple other notes:

Our syntax is case-insensitive, so if you'd like to creep out your co-workers, you can write something like this.

[dD#248 iN pRoGrEsS UnAsSIGNeD]Began fixing browser issue.

The DoneDone-specific syntax can appear anywhere in the commit message. It can appear at the end...

Began fixing browser issue. [dd#248 kawai.cheung@donedone.com in progress]

...or anywhere in the middle (if you really want to annoy your co-workers).

Began fixing [dd#248 kawai.cheung@donedone.com in progress] browser issue

You can also have multiple ones in a single commit if you want to update more than one task in a different way:

[dd#248 kawai.cheung@donedone.com in progress][dd#249 closed] I'm updating two tasks at once!

Two Common Scenarios

There are two common scenarios where you'd want to update tasks in a DoneDone project from Github. Let's go through both scenarios to see how the integration works:

1) Pushing one or more local commits to a remote repository

In a DoneDone project, I've been working on a few tasks (namely, #12, #13, and #14) in a branch. I made a few commits during the day and have just pushed up these commits to the remote branch. Here's what the commits look like in Github. As you can see, I ended on a high note, setting all three tasks to "Ready for next release" by the end of my work day.

And here is what DoneDone activity section and project task lists looks like after it receives the commit information from Github.

Additionally, because I made the push to the remote repository, I receive an email from DoneDone summarizing what happened.

If there are any problems with a DoneDone commit message (e.g. the assignee doesn't have access to the project, the status doesn't exist for the workflow associated to the project, or the Task # doesn't exist), the Github email summary will detail those along with a link to the direct commit. This lets you manually review any problems and update the tasks you meant to update directly in DoneDone, if necessary.

2) Merging a pull request to a parent branch

A second common scenario is when you want to merge a branch back to its parent branch.

Let's continue with the scenario above. Now that all three tasks (#12, #13, and #14) are "Ready for Next Release", I'd like to merge them into the parent branch so they can be reviewed on our staging environment by Michael. Here's the pull request message I make right before merging. As you can see, I want to re-assign all the tasks completed in this branch to Michael and change them to "Ready for Retest".

And here is what DoneDone activity section and project task lists looks like after it receives the merge update from Github.

Here's the DoneDone email summarizing what happened.

Connecting a Github repo to a DoneDone project

Getting a Github repository connected to a DoneDone project is simple: You will set up a webhook in your Github repo that points back to DoneDone.

First, go to the DoneDone project you want to connect. Click the Settings icon. Then click the Integrations link.

Next, open up the Github panel to view the configuration settings for the webhook. Make note of the four bits of information on your screen.

Now, go to your Github repository. Click on Settings (A). Then click on Webhooks (B). Finally, click the "Add webhook" button (C) as shown below.

Here, you'll configure the webhook. Remember the four bits of information above? Enter those values in the corresponding fields and then click "Add webhook".

That's it! Your repository is now connected to your DoneDone project. You should see updates occur whenever you push changes with the valid DoneDone syntax in your commit messages.

Common questions

• How do we timestamp updates? When DoneDone tasks are updated from a Github push or merge, the timestamp of the update will reflect the time the push or merge was made, not the time the commits were made. For example, if you've fixed up various bugs in a handful of local commits over the past week, when they are pushed to the remote repository, their timestamp in DoneDone will all be the same (when the push was made).
• What if the commit was made by someone not in DoneDone? DoneDone will still update tasks on commits made by people not in your account. In this case, their updates will appear from them, but naturally, they won't have access to the task unless you add them to your account.
• If a commit to a remote branch is then merged to its parent branch, will the commit be processed by DoneDone again? No. A commit is only ever acted upon by DoneDone once (we store each commit's unique Github ID so we know which ones we've already successfully processed. This allows you to merge pull requests and not have all the commits in your request process again. This also allows you to manually redeliver a push webhook, in case some other commits in a push failed initially, and only have the failed ones process.