Nbconvert issue triaging

Nbconvert has a lot of issues that are questions/stale/duplicates/untagged/fixed along with other issues but still open/issues without enough information. I want to go through these issues and clean it up, so that we can have a more clear idea of what the actual issues are and how we can focus our efforts. I want to be transparent about what I am going to do, and give others an opportunity for feedback before I start.

I want to

  • Close issues that are believed fixed and stale. I will right an explanation for closing, and asking to reopen if I made a mistake.
  • Re-title issues so that they indicate a specific problem (ex: bad “failure to convert to PDF”, good “remote images in PDF cause conversion to fail”)
  • tag issues
  • group duplicate issues
  • potentially add issues to the “6.0”, “wishlist”, and “no action” milestones

I think an issue template may be useful too.

CC @MSeal @mpacer


this would be amazing

1 Like

Sounds great, thanks @t-makaro!

One note, the default GitHub permissions don’t let users re-open issues. We usually ask folks to comment if they’d like an issue re-opened.

@blink1073 I believe only the original author of an issue can re-open, but yes, I can ask others to comment if they’d like it re-opened.

I’m afraid that’s not the case:

Disappointing, but thank you for pointing that out.

Thanks for putting this list of actions together @t-makaro! I’m strongly for the effort. I’d also say for really old tickets, let’s lean on closing unless it’s obvious it’s still an open issue. There’s a lot of issues that are ambiguous about cause and are so many versions old it’d be hard to say are still viable tickets. When we leave a closing message in this case we should ask for examples of failure with current versions of nbconvert and dependencies.


On the issue template, let’s do this sooner rather than later! It’d be highly beneficial to covering the basic questions like “Is this reproduced on the latest version of nbconvert?” and “do you have a working example you can post?”. The only thing I believe we should avoid is making a very long or process driven template. A few basics goes a long ways without impeding a users ability to communicate.


On the topic of templates, one thing we’ve tried (and is hard to measure but I think has worked OK) has been to have 3 templates:

  1. Bug report -> takes them to a bug report template
  2. Enhancement request -> takes them to a feature request template
  3. Questions -> Has a note to not ask questions in the github issues, and instead points them to the Community Forum for posting.

The hope is that we can boost the SNR in the github issues this way by having fewer open ended “how do I?” kinds of questions in there. Just a thought!

1 Like

For my education do you have an example of one? I dislike long templates so collecting anti-patterns is a hobby … :slight_smile:

If we are going to redirect users away from GitHub for asking questions, where shall we direct them too? The gitter chat gets to cluttered, and it is hard to search. I think this discourse would be a good option, but I think that we should make a category for nbconvert here if we do that.

This seems like a great idea that I strongly support. But as someone who went down this road, I have some tips as I’d love to see this succeed and it’s really easy to burn out trying to do this.

First, I would recommend breaking it into chunks. Don’t do more than a certain number (15? 20?) in a sitting. Most of them will be easy, but the tricky ones will be really tricky.

I would not try to do all of those tasks at the same time. Or if you do, expect to get relatively few done in a single sitting.

The grouping of duplicate issues is a particularly thorny problem as without a good structure to rely on, it can quickly become an n^2 problem. It would benefit you to have the tags & milestones in place before trying to group them into duplicates.

Closing issues that are believed to be fixed tends to require diving into the details of what’s being reported and it can be incredibly draining. The biggest problem for these activities are the common cases where an issue is originally reported as being about one topic, when it later evolves into a different topic as more folks weigh in.

Re-titling issues also faces the problem that the issue originally created may not be the issue as it evolves. However, in some cases, it’s not possible to have a single title that encompasses everything that is discussed. I never really figured out how to resolve that one… it’s by definition a bit intractable.

Milestones have less to do with the structure of issues and more to do with how the project organizes it’s progress. I think you should avoid trying to make those decisions as you go through this (even though it means doing a second pass later).

I hope the lessons I learned from earlier attempts end up helping this effort! This would be wonderful for the nbconvert community.


I found the fastai form a bit tedious in this regard when I had to open an issue there for an nbconvert failure that users were reporting.


Hi @t-makaro, Welcome and thanks for the desire to triage. For the JupyterHub repo, I have some pretty standard response when closing issues. I typically work from oldest to most recent. If something sits open greater than 4 months and does not seem actionable, I will either close with a message or warn that I will close in 30 days if no activity happens. Sometimes I will ask the original submitter to take a look and close if no longer relevant. Happy to pair with you on GitHub to get started. I wouldn’t redirect folks if possible to other places.

1 Like