Skip to content

Commit 18a943f

Browse files
committed
enhance roadmap
1 parent 9625738 commit 18a943f

2 files changed

Lines changed: 165 additions & 18 deletions

File tree

‎docs/assets/stylesheets/extra.css‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -219,8 +219,3 @@ body {
219219
width: 200px;
220220
}
221221
}
222-
223-
/* Roadmap: highlight the active (open) milestone row in the Milestone Summary table */
224-
.md-typeset table:not([class]) tr:has(> td .milestone-state-open) {
225-
background-color: rgba(18, 151, 49, 0.1);
226-
}

‎tools/roadmap-generator/index.js‎

Lines changed: 165 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -55,14 +55,61 @@ const symbols = {
5555
// Issue status
5656
done: '✔', // completed
5757
notDone: '⏳', // in progress
58+
canceled: '❌', // canceled / wontfix
5859
// Milestone status
59-
open: '🚀', // active
60+
open: '', // active
6061
closed: '🏁', // completed
6162
// Milestone details
6263
progress: '📋', // or 'Progress'
6364
date: '📅', // or 'Estimated Completion'
6465
}
6566

67+
// Label names (matched case-insensitively) that drive the issue status icons.
68+
// Adjust these to match the labels actually used in the repository.
69+
const CANCELED_LABELS = ['canceled', 'cancelled', 'wontfix']
70+
const IN_PROGRESS_LABELS = ['in progress', 'in-progress', 'in_progress']
71+
72+
// Shown in the Version column for shipped (closed) issues that have not yet
73+
// been cut into a release.
74+
const NEXT_RELEASE = 'upcoming'
75+
76+
// Whether an issue was closed without being shipped (labeled
77+
// canceled/cancelled/wontfix).
78+
function isCanceledIssue(issue) {
79+
const names = (issue.labels || []).map((label) => label.name.toLowerCase())
80+
return names.some((name) => CANCELED_LABELS.includes(name))
81+
}
82+
83+
// Status icon for a single issue. Canceled issues get the canceled icon,
84+
// in-progress issues get the notDone icon, completed issues (closed and not
85+
// canceled) keep the done icon, and everything else (open, not started) has
86+
// no icon.
87+
function issueIcon(issue) {
88+
if (isCanceledIssue(issue))
89+
return symbols.canceled
90+
const names = (issue.labels || []).map((label) => label.name.toLowerCase())
91+
if (names.some((name) => IN_PROGRESS_LABELS.includes(name)))
92+
return symbols.notDone
93+
if (issue.state !== 'open')
94+
return symbols.done
95+
return ''
96+
}
97+
98+
// Version (release tag) an issue was introduced in. Open issues and issues
99+
// closed without being shipped (labeled canceled/wontfix) have no version.
100+
// Other closed issues map to the first release cut on or after the date they
101+
// were closed (see buildVersionLookup); ones closed after the most recent
102+
// release are marked as "Next release".
103+
function issueVersion(issue, versionFor) {
104+
if (issue.state === 'open')
105+
return ''
106+
if (isCanceledIssue(issue))
107+
return ''
108+
if (!issue.closed_at || !versionFor)
109+
return ''
110+
return versionFor(issue.closed_at) || NEXT_RELEASE
111+
}
112+
66113
/* GITHUB */
67114

68115
// Github token
@@ -146,35 +193,140 @@ function fetchAllIssuesForRepo(client, repo) {
146193
return fetchPage(1)
147194
}
148195

196+
// Fetch every tag in a repo. The API clamps per_page to 100 (as with issues),
197+
// so pages are fetched until a short page is returned.
198+
function fetchAllTagsForRepo(client, repo) {
199+
const [owner, name] = repo.split('/')
200+
function fetchPage(page) {
201+
return client.request('GET /repos/{owner}/{repo}/tags', {
202+
owner: owner,
203+
repo: name,
204+
per_page: GITHUB_PAGE_SIZE,
205+
page: page
206+
})
207+
.then((res) => {
208+
if (res.data.length < GITHUB_PAGE_SIZE)
209+
return res.data
210+
return fetchPage(page + 1).then((rest) => res.data.concat(rest))
211+
})
212+
}
213+
return fetchPage(1)
214+
}
215+
216+
// Resolve each tag to the date its release commit was made (the moment that
217+
// version was cut) and return a function that maps an issue's close date to
218+
// the first release cut on or after that date i.e. the version the issue
219+
// was introduced in. Issues closed after the most recent release map to ''
220+
// (not yet released).
221+
function buildVersionLookup(client, repo, tags) {
222+
const [owner, name] = repo.split('/')
223+
return Promise.map(tags, (tag) => {
224+
return client.request('GET /repos/{owner}/{repo}/commits/{sha}', {
225+
owner: owner,
226+
repo: name,
227+
sha: tag.commit.sha
228+
})
229+
.then((res) => ({
230+
name: tag.name,
231+
date: moment.utc(res.data.commit.committer.date)
232+
}))
233+
}, { concurrency: 16 })
234+
.then((releases) => {
235+
// Oldest release first so the first match is the introducing version.
236+
releases.sort((a, b) => a.date.valueOf() - b.date.valueOf())
237+
return (closedAt) => {
238+
const closed = moment.utc(closedAt).valueOf()
239+
for (const release of releases) {
240+
if (release.date.valueOf() >= closed)
241+
return release.name
242+
}
243+
return ''
244+
}
245+
})
246+
}
247+
248+
// Sort a milestone's issues: shipped (closed, not canceled) issues come
249+
// first with the most recently closed on top, then open issues (oldest
250+
// created first), with canceled issues at the bottom (most recently closed
251+
// first).
252+
function sortMilestoneIssues(issues) {
253+
const toTime = (value) => (value ? moment.utc(value).valueOf() : null)
254+
// Group rank: shipped closed issues first, open issues in the middle,
255+
// canceled issues last.
256+
const rank = (issue) => {
257+
if (isCanceledIssue(issue))
258+
return 2
259+
if (issue.state === 'open')
260+
return 1
261+
return 0
262+
}
263+
issues.sort((a, b) => {
264+
const aRank = rank(a)
265+
const bRank = rank(b)
266+
if (aRank !== bRank)
267+
return aRank - bRank
268+
if (aRank === 1) {
269+
// Order open issues by creation date (oldest first)
270+
const atA = toTime(a.created_at) || 0
271+
const atB = toTime(b.created_at) || 0
272+
return atA - atB
273+
}
274+
// Order closed issues by when they were closed (most recent first,
275+
// missing close dates last)
276+
const atA = toTime(a.closed_at) || Number.MIN_SAFE_INTEGER
277+
const atB = toTime(b.closed_at) || Number.MIN_SAFE_INTEGER
278+
return atB - atA
279+
})
280+
}
281+
149282
function getAllMilestoneIssues(client, project) {
150283
logger.log(`-- Generate issues list for '${project.name}' --`)
151284
let result = _.cloneDeep(project)
285+
// Release tags are only fetched when the goals are listed, since they are
286+
// only used to derive the version each goal was introduced in.
287+
const wantVersions = !!argv.goals
152288
return Promise.map(project.repos, (repo) => {
153289
logger.log(`Get issues from ${repo}`)
154-
return fetchAllIssuesForRepo(client, repo)
155-
.then((issues) => {
290+
const versionPromise = wantVersions
291+
? fetchAllTagsForRepo(client, repo).then((tags) => buildVersionLookup(client, repo, tags))
292+
: Promise.resolve(null)
293+
return Promise.all([
294+
fetchAllIssuesForRepo(client, repo),
295+
versionPromise
296+
])
297+
.then(([issues, versionFor]) => {
156298
logger.log(`Found ${issues.length} issues in ${repo}`)
157-
return { repo: repo, issues: issues }
299+
return { repo: repo, issues: issues, versionFor: versionFor }
158300
})
159301
}, { concurrency: 16 })
160302
.then((res) => {
161-
res.forEach((repo) => {
162-
repo.issues.forEach((e) => {
303+
res.forEach((r) => {
304+
r.issues.forEach((e) => {
163305
if (e.milestone) {
164306
const milestone = result.milestones[e.milestone.title]
165307
if (milestone) {
166308
milestone.issues.push({
167309
title: e.title,
168-
repo: repo.repo,
310+
repo: r.repo,
169311
html_url: e.html_url,
170312
repository_url: e.repository_url,
171313
state: e.state,
172-
labels: e.labels
314+
labels: e.labels,
315+
// Version (release tag) the issue was introduced in, derived
316+
// from its close date and the repo's release tags.
317+
version: issueVersion(e, r.versionFor),
318+
// Kept for ordering only: closed issues are listed in the
319+
// order they were closed (see sortMilestoneIssues)
320+
closed_at: e.closed_at,
321+
created_at: e.created_at
173322
})
174323
}
175324
}
176325
})
177326
})
327+
// List shipped closed issues first (most recent first), open issues
328+
// next, canceled issues last
329+
Object.keys(result.milestones).forEach((k) => sortMilestoneIssues(result.milestones[k].issues))
178330
return result
179331
})
180332
}
@@ -211,7 +363,7 @@ function generateMilestonesSummary(project, options) {
211363

212364
let milestone = ''
213365
// Marker class so extra.css can highlight the active milestone row
214-
milestone += `| <span class="milestone-state milestone-state-${m.state}">${m.state === 'open' ? symbols.open : symbols.closed}</span> `
366+
milestone += `| <span>${m.state === 'open' ? symbols.open : symbols.closed}</span> `
215367
milestone += `| **[${m.title}](#${nameToAnchor(m.title)})** `
216368

217369
if (opts.useVisualProgressBars)
@@ -263,12 +415,12 @@ function dataToMarkdown(projects, options) {
263415
milestone += `${symbols.date} &nbsp;&nbsp;**${moment.utc(m.due_on).format('MMM DD YYYY')}**\n\n`
264416

265417
if (opts.listGoalsPerMilestone) {
266-
milestone += `| Status | Goal | Labels |\n`
267-
milestone += `| :---: | :--- | --- |\n`
418+
milestone += `| Status | Goal | Version |\n`
419+
milestone += `| :---: | :--- | :---: |\n`
268420
milestone += m.issues.map((issue, idx) => {
269-
let text = `| ${issue.state === 'open' ? symbols.notDone : symbols.done} `
421+
let text = `| ${issueIcon(issue)} `
270422
text += `| [${issue.title}](${issue.html_url}) `
271-
text += issue.labels.length > 0 ? `| ` + issue.labels.map((label) => `\`${label.name}\``).join(', ') : '| '
423+
text += issue.version ? `| \`${issue.version}\`` : '| '
272424
text += '|\n'
273425
return text
274426
}).join('') + '\n'

0 commit comments

Comments
 (0)