How to create finely-grained issues

Engineering NuPIC
1

I have a problem. Actually, the NuPIC project has a problem, but it affects me a lot as project manager. The problem is there are too many large issues that are not properly broken up into small bits. You might think that putting in the extra work to break issues up into small parts is not worth the effort, but it totally is. Here’s why.

  1. small-scoped issues turn into small code changes
  2. small code changes turn into small PRs
  3. small PRs are easier to review
  4. easy to review PRs get merged or rejected faster

This means we all waste less time in the long run, because you put in the effort to break up an issue into small tasks. It’s a win/win.

The worst thing for me as project manager for NuPIC is seeing a huge stale pull request get closed without being merged. This has happened several times in the past, and each time it was like a :knife: twisting in my :heart:. It makes contributors go away (@david-ragazzi :cry:), it discourages new contributions, and it wastes everybody’s time all around.

Here’s how I want to see it happen in the future…

Let’s say you have a Big Idea for a change to NuPIC. It involves touching a lot of code, or building something new, but it’s not a small task, and people are probably going to have feedback on it.

First Open A Discussion

And this is the place to do it. Yes, you could create a Github issue first, and we could all discuss the issue there, but your Big Idea deserves to be vetted a little before formally describing it. Let our developer community tell you what they think! They might provide you with a better problem definition or even a better possible solution.

Of course, you might get shut down immediately, which is actually better than creating an Issue, coding up a solution, creating a PR, just to get it shot down by a @reviewer in the final stages. If you discuss Big Idea here, it will transition into Github Issues in a more mature state. If you get shot down, at least you got shot down before you worked on it (or you can work on it in community.research, which is really underutilized IMO).

Break it into small tasks

Before you run to Github to create you issue, take some time to analyze the tasks that will be required to accomplish Big Idea. Don’t focus on the solutions and the implementation details! That is the biggest mistake when defining issues. An issue should describe a problem that needs solving, a feature that needs to be added, or a specific bug that should be fixed. How that happens is not your concern when writing up the issue descriptions.

Each small task defined for the Big Idea should be as stand-alone as possible. This means that different people should be able to take on different small tasks within Big Idea. The small tasks might depend on each other, of course (you can’t count to 10 without going through 7,8,9 first). But the small tasks should be defined as much as possible in their own context.

By the end of this exercise, you should have one Big Idea and many small tasks in your head. All the small tasks must be accomplished in order to implement the Big Idea, and once they are all done, you can call Big Idea complete.

Create Big Idea issue in Github

This will be your “super” issue. It should describe at a high level the objective of Big Idea, how it will make things better, and exactly what functionality will change as a consequence of Big Idea being implemented. You’ll be editing this issue later to add links to the small tasks.

Create the small task issues in Github

For each small task, create a new Github Issue. Remember it should be as isolated as possible from both the super issue and sibling issues. Try to describe the feature in a way that would help another developer implement it. Imagine that you might not be the person to work on it.

Link the Super issue to the Sub-tasks

From the Big Idea super issue description, add a section to link to all the issues you created for the small tasks. (I will likely edit behind you to clean up the sub-task formatting because I am anal-retentive about that stuff.)

General Issue Creation Tips

Do not apply implementation requirements in the issue. The Issue is to describe the problem, not the solution. Potential solutions can be discussed in the Issue’s comments, not in the description. Specific details about solution implementations can be discussed in subsequent pull requests.

Now you’re in a good situation to start working!

  • You know what other contributors think about your Big Idea.
  • You are more likely to get help because you broke tasks out and defined them distinctly.
  • You know what order the work must be done in, so you can focus on one PR at a time.
  • Each PR will be reviewed faster because it is small and doing only one thing.
2 Likes
2

I have to bring up a “case in point”.

This issue included a ton of different ways to clean up encoders. That’s great, but @breznak did not create any subtasks. So, subsequently, discussion about all possible options continued on the issue, which is really confusing.

I just spent more than 30 minutes creating concrete subtasks and trying to move the individual conversations about each subtask there.

If Marek had created subtasks properly for this issue as described above and in our wiki, each conversation would have been properly isolated and easier to follow. This gives us a chance to review each part of the proposal separately and keep those conversations segregated.

As I stated in this comment:

The larger an issue gets, the harder it is to grok it. The less likely it is that another contributor will bother to read through it.

I hate to pick on you @breznak, but you are the worst about this! :stuck_out_tongue:

1 Like