Support rendering of proposal tables
Will
4 years ago
committed by
Richard van der Hoff
parent
e88a18ca5d
commit
643cdd19c8
@ -0,0 +1,81 @@
|
|||||||
|
{{/*
|
||||||
|
|
||||||
|
This template is used to render tables of MSC proposals.
|
||||||
|
|
||||||
|
It expects there to be a "proposals.json" under /data/msc.
|
||||||
|
It expects "proposals.json" to contain an array of objects,
|
||||||
|
one for each MSC state. Each object contains:
|
||||||
|
* `title`: human-readable title for the state, like "Proposal In Review"
|
||||||
|
* `label`: the GitHub label used for the state, like "proposal-in-review"
|
||||||
|
* `proposals`: an array of objects, each of which represents an MSC and contains:
|
||||||
|
* `number`: GitHub issue number
|
||||||
|
* `url`: GitHub URL for this issue
|
||||||
|
* `title`: Issue title
|
||||||
|
* `created_at`: issue creation date
|
||||||
|
* `updated_at`: issue last-updated date
|
||||||
|
* `authors`: array of GitHub user names representing authors of this MSC
|
||||||
|
* `shepherd`: GitHub user name representing the shepherd of this MSC, or null
|
||||||
|
* `documentation`: Links to further documentation referenced in the GitHub issue
|
||||||
|
|
||||||
|
This data is scraped from GitHub using the /scripts/proposals.js Node script.
|
||||||
|
The script is run in CI: so typically if you run a local server the data will
|
||||||
|
be missing and no tables will be generated. If you do want to see the tables locally,
|
||||||
|
you can run the script locally:
|
||||||
|
|
||||||
|
npm install
|
||||||
|
npm run get-proposals
|
||||||
|
|
||||||
|
If this template does find the data, it renders one table for each MSC state,
|
||||||
|
containing a row for each MSC in that state.
|
||||||
|
|
||||||
|
*/}}
|
||||||
|
|
||||||
|
{{ $states := .Site.Data.msc.proposals }}
|
||||||
|
|
||||||
|
{{ range $states }}
|
||||||
|
<h3 id="{{.label}}" class="proposal-table-title">{{ .title }}</h3>
|
||||||
|
{{ if .proposals }}
|
||||||
|
<table class="msc-table table">
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>MSC</th>
|
||||||
|
<th>Title</th>
|
||||||
|
<th>Created at</th>
|
||||||
|
<th>Updated at</th>
|
||||||
|
<th>Docs</th>
|
||||||
|
<th>Author</th>
|
||||||
|
<th>Shepherd</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
|
||||||
|
<tbody>
|
||||||
|
{{ range .proposals }}
|
||||||
|
|
||||||
|
{{ $index := 0 }}
|
||||||
|
{{ $docs_links_list := slice }}
|
||||||
|
{{ range .documentation }}
|
||||||
|
{{ $index = add $index 1 }}
|
||||||
|
{{ $docs_link := printf "<a href=\"%s\">%d</a>" . $index }}
|
||||||
|
{{ $docs_links_list = $docs_links_list | append $docs_link }}
|
||||||
|
{{ end }}
|
||||||
|
{{ $docs_links := delimit $docs_links_list ", " }}
|
||||||
|
|
||||||
|
{{ $authors_list := apply .authors "printf" "<a href=\"https://github.com/%s\">@%s</a>" "." "." }}
|
||||||
|
{{ $authors := delimit $authors_list ", " }}
|
||||||
|
|
||||||
|
<tr>
|
||||||
|
<td><a href="{{ .url }}">{{ .number }}</a></td>
|
||||||
|
<td>{{ .title }}</td>
|
||||||
|
<td>{{ .created_at }}</td>
|
||||||
|
<td>{{ .updated_at }}</td>
|
||||||
|
<td>{{ with $docs_links }}{{ $docs_links }}{{ end }}</td>
|
||||||
|
<td>{{ $authors }}</td>
|
||||||
|
<td>{{ with .shepherd }}<a href="https://github.com/{{ . }}">@{{ . }}</a>{{ end }}</td>
|
||||||
|
</tr>
|
||||||
|
{{ end }}
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
{{ else }}
|
||||||
|
<p>No MSCs are currently in this state.</p>
|
||||||
|
{{ end }}
|
||||||
|
{{ end }}
|
||||||
@ -0,0 +1,219 @@
|
|||||||
|
"use strict";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* This Node script fetches MSC proposals and stores them in /data/msc,
|
||||||
|
* so they can be used by a Hugo template to render summary tables of them
|
||||||
|
* in the specification.
|
||||||
|
*
|
||||||
|
* In detail, it:
|
||||||
|
* - fetches all GitHub issues from matrix-doc that have the `proposal` label
|
||||||
|
* - groups them by their state in the MSC process
|
||||||
|
* - does some light massaging of them so it's easier for the Hugo template to work with them
|
||||||
|
* - store them at /data/msc
|
||||||
|
*/
|
||||||
|
|
||||||
|
// built-in modules
|
||||||
|
const path = require('path');
|
||||||
|
const fs = require('fs');
|
||||||
|
|
||||||
|
// third-party modules
|
||||||
|
const fetch = require('node-fetch');
|
||||||
|
|
||||||
|
// We will write proposals into the /data/msc directory
|
||||||
|
const outputDir = path.join(__dirname, "../data/msc");
|
||||||
|
|
||||||
|
/**
|
||||||
|
* This defines the different proposal lifecycle states.
|
||||||
|
* Each state has:
|
||||||
|
* - `label`: a GitHub label used to identify issues in this state
|
||||||
|
* - `title`: used for things like headings in renderings of the proposals
|
||||||
|
*/
|
||||||
|
const states = [
|
||||||
|
{
|
||||||
|
label: "proposal-in-review",
|
||||||
|
title: "Proposal In Review"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "proposed-final-comment-period",
|
||||||
|
title: "Proposed Final Comment Period"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "final-comment-period",
|
||||||
|
title: "Final Comment Period"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "finished-final-comment-period",
|
||||||
|
title: "Finished Final Comment Period"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "spec-pr-missing",
|
||||||
|
title: "Spec PR Missing"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "spec-pr-in-review",
|
||||||
|
title: "Spec PR In Review"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "merged",
|
||||||
|
title: "Merged"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "proposal-postoned",
|
||||||
|
title: "Postponed"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "abandoned",
|
||||||
|
title: "Abandoned"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "obsolete",
|
||||||
|
title: "Obsolete"
|
||||||
|
}
|
||||||
|
];
|
||||||
|
|
||||||
|
let issues = [];
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Fetch all the MSC proposals from GitHub.
|
||||||
|
*
|
||||||
|
* GitHub only lets us fetch 100 items at a time, and it gives us a `link`
|
||||||
|
* response header containing the URL for the next batch.
|
||||||
|
* So we will keep fetching until the response doesn't contain the "next" link.
|
||||||
|
*/
|
||||||
|
async function getIssues() {
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A pretty ugly function to get us the "next" link in the header if there
|
||||||
|
* was one, or `null` otherwise.
|
||||||
|
*/
|
||||||
|
function getNextLink(header) {
|
||||||
|
const links = header.split(",");
|
||||||
|
for (const link of links) {
|
||||||
|
const linkPieces = link.split(";");
|
||||||
|
if (linkPieces[1] == ` rel=\"next\"`) {
|
||||||
|
const next = linkPieces[0].trim();
|
||||||
|
return next.substring(1, next.length-1);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
let pageLink = "https://api.github.com/repos/matrix-org/matrix-doc/issues?state=all&labels=proposal&per_page=100";
|
||||||
|
while (pageLink) {
|
||||||
|
const response = await fetch(pageLink);
|
||||||
|
const issuesForPage = await response.json();
|
||||||
|
issues = issues.concat(issuesForPage);
|
||||||
|
const linkHeader = response.headers.get("link");
|
||||||
|
pageLink = getNextLink(linkHeader);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
getIssues().then(processIssues);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Rather than just store the complete issue, we'll extract
|
||||||
|
* only the pieces we need.
|
||||||
|
* We'll also do some transformation of the issues, jsut because
|
||||||
|
* it's easier to do in JS than in the template.
|
||||||
|
*/
|
||||||
|
function getProposalFromIssue(issue) {
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A helper function to fetch the contents of special
|
||||||
|
* directives in the issue body.
|
||||||
|
* Looks for a directive in the format:
|
||||||
|
* `^${directiveName}: (.+?)$`, returning the matched
|
||||||
|
* part or null if the directive wasn't found.
|
||||||
|
*/
|
||||||
|
function getDirective(directiveName, issue) {
|
||||||
|
const re = new RegExp(`^${directiveName}: (.+?)$`, "m");
|
||||||
|
const found = issue.body.match(re);
|
||||||
|
return found? found[1]: null;
|
||||||
|
}
|
||||||
|
|
||||||
|
function getDocumentation(issue) {
|
||||||
|
const found = getDirective("Documentation", issue);
|
||||||
|
if (found) {
|
||||||
|
return found.split(",").map(a => a.trim());
|
||||||
|
} else {
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function getAuthors(issue) {
|
||||||
|
const found = getDirective("Author", issue);
|
||||||
|
if (found) {
|
||||||
|
return found.split(",").map(a => a.trim().substr(1));
|
||||||
|
} else {
|
||||||
|
return [`${issue.user.login}`];
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function getShepherd(issue) {
|
||||||
|
const found = getDirective("Shepherd", issue);
|
||||||
|
if (found) {
|
||||||
|
return found.substr(1);
|
||||||
|
} else {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return {
|
||||||
|
number: issue.number,
|
||||||
|
url: issue.html_url,
|
||||||
|
title: issue.title,
|
||||||
|
created_at: issue.created_at.substr(0, 10),
|
||||||
|
updated_at: issue.updated_at.substr(0, 10),
|
||||||
|
authors: getAuthors(issue),
|
||||||
|
shepherd: getShepherd(issue),
|
||||||
|
documentation: getDocumentation(issue)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the intersection of two arrays.
|
||||||
|
*/
|
||||||
|
function intersection(array1, array2) {
|
||||||
|
return array1.filter(i => array2.includes(i));
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Given all the GitHub issues with a "proposal" label:
|
||||||
|
* - group issues by the state they are in, and for each group:
|
||||||
|
* - extract the bits we need from each issue
|
||||||
|
* - write the result under /data/msc
|
||||||
|
*/
|
||||||
|
function processIssues() {
|
||||||
|
if (!fs.existsSync(outputDir)){
|
||||||
|
fs.mkdirSync(outputDir);
|
||||||
|
}
|
||||||
|
const output = [];
|
||||||
|
// make a group of "work in progress" proposals,
|
||||||
|
// which are identified by not having any of the state labels
|
||||||
|
const stateLabels = states.map(s => s.label);
|
||||||
|
const worksInProgress = issues.filter(issue => {
|
||||||
|
const labelsForIssue = issue.labels.map(l => l.name);
|
||||||
|
return intersection(labelsForIssue, stateLabels).length === 0;
|
||||||
|
});
|
||||||
|
output.push({
|
||||||
|
title: "Work In Progress",
|
||||||
|
label: "work-in-progress",
|
||||||
|
proposals: worksInProgress.map(issue => getProposalFromIssue(issue))
|
||||||
|
});
|
||||||
|
// for each defined state
|
||||||
|
for (const state of states) {
|
||||||
|
// get the set of issues for that state
|
||||||
|
const issuesForState = issues.filter(msc => {
|
||||||
|
return msc.labels.some(l => l.name === state.label);
|
||||||
|
});
|
||||||
|
// store it in /data
|
||||||
|
output.push({
|
||||||
|
title: state.title,
|
||||||
|
label: state.label,
|
||||||
|
proposals: issuesForState.map(issue => getProposalFromIssue(issue))
|
||||||
|
});
|
||||||
|
}
|
||||||
|
const outputData = JSON.stringify(output, null, '\t');
|
||||||
|
const outputFile = path.join(outputDir, `proposals.json`);
|
||||||
|
fs.writeFileSync(outputFile, outputData);
|
||||||
|
}
|
||||||
Loading…
Reference in New Issue