github issues and spec pointers

Hi folks,

 

Cleaning up the pointers to github issues in the specification yesterday,
there were a few practices I thought it might be good to point out for
future reference:

 

1.       Try to ensure that issue titles say as much about the problem
you're raising as you can. When we add a pointer, the issue number and title
become the link, so it's the most prominent thing reviewers will see. If
it's clear we can't resolve an issue and it will be left open, don't be
afraid to go back and edit the title if it can be improved.

 

2.       Try to keep the initial description of an issue short and succinct.
Respec will pull in the first comment automatically when we add a pointer,
but if it's too long we have to replace with a shorter blurb.

 

3.       This gets said a lot, but just another plea to try and keep issues
focused on a single topic. I realize this is sometimes difficult to do, and
the early days of meandering issues are passing, but looking ahead to review
of the specification it will make life easier if all posts to an issue are
directly related to it. Trying to follow the discussion gets difficult when
it spawns new threads. If a new discussion begins to diverge, just open a
new issue and reference where it started. It also helps maintenance when the
primary issue closes and a side issue needs to remain open.

 

Thanks for your attention,

 

Matt