Pull in issue tracker data using GitHub API

[anssiko]

ReSpec has a feature that allows to pull in data using the GitHub API. This PR makes use of that feature and pulls open issue data directly from GH issues into the spec. This change should make it easier for us to keep the spec and GH issues in sync, as the latter will be the canonical source for all issue data. Any changes done to the GH issues (specifically, its topic or the first comment) will be automatically pulled into the latest spec.

For example, the following markup in the ReSpec source:

<div class="issue" data-number="35"></div>

Is turned into the following markup automatically:

<div class="issue" id="issue-35">
  <div class="issue-title" aria-level="5" role="heading" id="h-issue1">
    <a href="https://www.github.com/w3c/presentation-api/issues/35">
    <span>ISSUE 35</span></a>:    
    Refine how to do session teardown/disconnect/closing
  </div>
    <p>
      There are rough edges [... first comment in the respective GH issue ...].
    </p>
</div>

@mfoltzgoogle Please review and merge if you're happy with the change.

[mounirlamouri]

Did you remove the text on purpose?

[anssiko]

#9 should have the same text.

[mounirlamouri]

Thanks for the generated HTML. The issue summary looks a bit too verbose but I guess it will be fixed if we actually fix the issues ;)

LGTM

[anssiko]

That was the idea -- by making the issues more visible in the spec we put a bit of pressure on the group to fix them :-)

We can amend and embellish the issue summaries as we roll on, make them prettier.

[mfoltzgoogle]

I am not sure this is a positive change. It appears that the effective change is to pull the first comment from the GH issue into the document, which could be quite long and out of context. As is, the change hurts readability.

I would be okay with this approach with two modifications:

• Change the integration to omit the summaries and only include the issue title.
• Have ReSpec omit the issue when the issue is closed on GH.

If these aren't possible, I would like to revert this change to the prior approach, where the issues are just links to GH where the reader can see the entire issue thread in context.

[anssiko]

@mfoltzgoogle Would your first concern be addressed if the first comment of each issue that is pulled in the spec would be edited in GH issues to be worded as such that it is fine for inclusion into the spec while further elaboration would be placed in the follow up comments? We've used this integration in some other specs and I personally felt keeping GH issues in sync with the spec makes the editor's life easier since it minimizes information duplication. The only tradeoff I noticed is that since this information is pulled from GH into the spec dynamically the source itself does not include the issue text, source diff for issue text changes is not possible unless we generate an HTML from the source on each commit (we do that with ReSpec for some specs).

I think the second concern is already addressed i.e. closed issues are not rendered, but it would probably still make sense to drop the issue placeholder <div>s from the specification when the corresponding issue is closed similarly to as we'd do even without this integration.

If the above does not address the concerns and you feel this integration is not actually helping you as an editor feel free to revert. It is always the editor who has the final say on the toolchain issues :-)

[mfoltzgoogle]

I'm not sure, if we edited every referenced issue as described wouldn't we lose some information (or lose the correct chronological sequence of comments)?

Auto-removal of closed issues is nice, but since the initial comment in a GH issue rarely changes, I'm not sure there's a lot of synchronization required.

[anssiko]

@mfoltzgoogle I submitted #174 to address your first concern.