How to manage your work on GitHub with Smos

Date 2021-05-19

Smos has recently gotten a new companion tool called smos-github, which allows for easier integration of your self-management workflow with GitHub. In this post I will propose a sample workflow for developers to keep track of, and follow up on, the issues and pull requests that they are involved in. We assume a basic working knowledge of how to implement GTD in Smos.

Managing software projects using self-management projects

The term 'project' is a bit overloaded here, because in software "smos" would be considered one project. However, using a granularity as coarse as that will prove unhelpful in the context of self-management. Instead, we recommend using a single issue and/or pull request as the granularity of a project in self-management. For example, you might have an our-app/static-builds.smos or our-app/issue-256.smos project file in your workflow, but not just an our-app.smos project file.

Pieces to manage

Writing code involves more than just writing committing code to a GitHub repository. A sustainable real-world development process involves tracking issues, discussions, code review, CI, CD, follow-up with the stakeholders, etc. The self-management approach that you use should be able to deal with all of these pieces, not just the code.

An example project

To explain the workflow that I propose, I will use this issue as an example. This issue was opened by someone who noticed a bug in smos-sync-client on Mac OS. After a bit of back and forth, they created a PR with a fix which required review. The problem was fixed and the fix added to the changelog.

From a self-management perspective, the requirements are:

  • When I first get the issue, I need to process it to decide what to do with it

  • When I write a comment and expect a response, I need to be able to wait for a response in such a way that I can forget about it until 1. the answer comes in or 2. I need to send a reminder.

  • When I write a PR, I need to be able to wait for a review in such a way that I can forget about it until 1. I get a review or 2. I need to send a reminder.

Using smos, these requirements can be fulfilled using the WAITING state, the url property and optionally the new smos-github tool.

Workflow using Smos

When I first get the issue, GitHub sends me a notification to my inbox. From there I can process it and write up a smos project.

──[ Editor: workflow/projects/smos/issue-202 ]──
  TODO Issue 202 [0/1]
  goal: Fix syncing on macos
  ❯ NEXT Investigate to see if I can find the bug

After a bit of investigating, I decide that I need to ask the bug reporter some questions, so I write my questions into the issue discussion and use the convDoneAndWaitForResponse action (<space>nw, by default) to mark my investigation entry as DONE and create a WAITING entry to wait for a response. I also add the url property and refer to the comment that I'm waiting for a response on.

──[ Editor: workflow/projects/smos/issue-202 ]──
  TODO Issue 202 [1/2]                                                              
  goal: Fix syncing on macos
    DONE Investigate to see if I can find the bug
  ❯ WAITING for a response from the issue reporter                                  
    url: https://github.com/NorfairKing/smos/issues/202#issuecomment-830430193  

Now I can select the entry with the url property and activate the convOpenUrl action (<space>ou, by default) to open the issue in my browser to see if I have gotten a response yet. However, we can let smos-github do this for us.

$ smos-github list
file                          state    header                                  owner        repo  number  state   update
projects/smos/issue-202.smos  WAITING  for a response from the issue reporter  NorfairKing  smos  202     open    waiting

Now the entry will be treated as any other WAITING entry: It will show up in your waiting report and it will show up in your work report when it's overdue. On top of that, the smos-github list command will show you in the update column whether it is your turn to do something. Indeed, when I get a response to my question, the update column will show ready like this:

$ smos-github list
file                          state    header                                  owner        repo  number  state   update
projects/smos/issue-202.smos  WAITING  for a response from the issue reporter  NorfairKing  smos  202     open    ready

(In practice, you don't need the smos-github tool, but it can be very helpful to check on all GitHub issues and pull requests during your weekly review.

Now that I have enough information to continue, I have a next action again, and I add the link to the latest comment to it:

──[ Editor: workflow/projects/smos/issue-202 ]──
  TODO Issue 202 [2/3]
  goal: Fix syncing on macos
    DONE Investigate to see if I can find the bug
    DONE for a response from the issue reporter
    url: https://github.com/NorfairKing/smos/issues/202#issuecomment-830430193
  ❯ NEXT make a PR with the fix
    url: https://github.com/NorfairKing/smos/issues/202#issuecomment-830641556

Once I've made my PR, I can add another waiting action and link to it with the url property again:

──[ Editor: workflow/projects/smos/issue-202 ]──
  TODO Issue 202 [3/4] 
  goal: Fix syncing on macos
    DONE Investigate to see if I can find the bug
    DONE for a response from the issue reporter
    url: https://github.com/NorfairKing/smos/issues/202#issuecomment-830430193
    DONE make a PR with the fix
    url: https://github.com/NorfairKing/smos/issues/202#issuecomment-830641556
  ❯ WAITING for a review on this PR
    url: https://github.com/NorfairKing/smos/pull/203  

This last entry WAITING entry works the same way as any other WAITING entry, just like before, and smos-github list will show ready when the PR has received a review.

Now the back and forth can continue until the PR is merged, the issue closed, and the smos project archived.

Previous
The undefined trick

Know a technical team that could use strong technical leadership?

Hire me
Next
The ci.nix pattern