Automate the monitoring of chapter progress

[rviscomi]

This is a stretch, but I'd love to hear if anyone is interested to work on a small project like this.

Problem

GitHub has a few features that make project management easier, like project boards and support for checkboxes to track issue progress. One challenge I had last year managing the project, and will continue to be a challenge this year, is keeping on top of 20+ chapters' worth of progress updates.

Proposal

I would love to be able to automate some of this chapter monitoring so I have a single view where I can see how far along each chapter is at a glance, in terms of hitting milestones. The GitHub API has support for getting issue comments, so I can imagine a system that fetches the first comment of each chapter issue, parses the status of each milestone's checkbox, and saves the results to a grid of chapters/milestones.

One approach could be to create a Google Sheet with each chapter and its corresponding issue number. Then an Apps Script function periodically queries each issue and writes the status of each chapter's milestone to columns in the sheet.

Another approach could be to have a central GitHub issue that is automatically updated based on GitHub actions or something that can listen for edits to the specific issue comments and modify the central issue.

Any other ideas? Would anyone be interested in building this? cc @OBTo @HTTPArchive/developers

[max-ostapenko]

Is this something that provides you with an idea about chapter progress: https://github.com/HTTPArchive/almanac.httparchive.org/milestone/7

It's a list of issues per milestone, and each chapter issue has little visualisation of checklist progress.

If not, what is missing?

[rviscomi]

Thanks @max-ostapenko, I'm looking for a way to see exactly which checkboxes were checked, not just how many. Other valuable metadata in the chapter issues include the markdown table of authors/reviewers/analysts. It'd be great to parse those out as well so we can stay on top of staffing changes.

[rviscomi]

@ibnesayeed you have experience with GH Actions, any chance you'd be interested to work on this?

[ibnesayeed]

@ibnesayeed you have experience with GH Actions, any chance you'd be interested to work on this?

Once we figure out how exactly do we want to poll and track changes, then I can help with the GH Actions part. These days I am busy working on some priority deadlines, so it is a little difficult for me to take the full responsibility of the task.

[ibnesayeed]

I attempted to implement this proposal in #990. I hope it makes your life easier and reports the progress the way you would like.

Cool, I assume this is related to #943? We should sync up about how to display the progress of each chapter. -- @rviscomi #989 (comment)

Yes, #898 is an issue I created to display consolidated progress report. Perhaps it will be a good idea to discuss progress there and not how it is reported (that's why cross-quoted your comment here). Let's discuss technical aspects here in this thread or in the PR thread #990. I needed that placeholder issue before I could push the PR, otherwise I would have created that issue after the PR was reviewed.

[rviscomi]

Ahhh gotcha, that makes sense. What I would love to see is a table like this:

Chapter	Draft	1	2	3	4	5	6	7	8	9	10
JavaScript	Doc	☑	☑	☑	☑
CSS	Doc	☑	☑
Markup	Doc	☑	☑	☑
Media	Doc	☑	☑	☑
Third Parties	Doc	☑	☑	☑
Fonts	Doc	☑	☑
Cookies	Doc	☑	☑	☑	☑
WebAssembly	Doc	☑	☑
Jamstack	Doc	☑	☑	☑
Performance	Doc	☑	☑
Security	Doc	☑	☑
Accessibility	Doc	☑	☑
SEO	Doc	☑	☑
PWA	Doc	☑	☑
Mobile Web	Doc	☑	☑
Design	Doc	☑	☑
Capabilities	Doc	☑	☑
Privacy	Doc	☑
Ecommerce	Doc	☑	☑
CMS	Doc	☑
Compression	Doc	☑	☑
Caching	Doc	☑	☑	☑
CDN	Doc
Page Weight	Doc
Resource Hints	Doc	☑	☑
HTTP/2	Doc	☑	☑	☑	☑

Where the chapter name is a link to the issue and "Doc" is a link to the [~draft-doc] URL. How does that sound?

Thanks for working on this!

(Edit: After seeing your mockup in #990 the numbered columns seem to work nicely. Updated my table to use those instead.)

[ibnesayeed]

(Edit: After seeing your mockup in #990 the numbered columns seem to work nicely. Updated my table to use those instead.)

I opted for a full grid instead of just reporting the next milestone to give a better overall comparative picture in an aligned manner, because otherwise we will end up parsing text which will be difficult to realize in a quick glance.

I used the ☐ character for tasks that are not done yet (for the sake of completeness as the two related Unicode characters represent ballot box and checked ballot box), but if you prefer I can make them empty.

I did not add rest of the metadata like link to the draft or the chapter lead because I thought we were keeping the summary simple and can go to the actual chapter tracker for more details. If these entries are easy to parse then there should be no issues adding them, However, the more hard-coding and assumptions we make, the less flexible and brittle the system will become, should things change in the future.

[ibnesayeed]

And yes, I did link each chapter name with the corresponding issue (which was sensible and obvious thing to do). I also removed the repeated suffix of 2020 from each issue title which would otherwise making the table unnecessarily wider. Well, I replaced any trailing sequence of digits and space before that with nothing, so this can be used in the future as well without much changes.

[rviscomi]

Yeah you're right, the grid of checkboxes is more compact than I thought and it looks better than text. Mapping milestone numbers is a good workaround. 👏

I'm ok doing without the ☐ character. It appears a totally different size than the checked box in GitHub's font, so I don't see a lot of value in keeping it: ☐ ☑ ☐ ☑

At the bottom of every issue we define the [~draft-doc] URL consistently, so it should be easy to parse. We can update the action if this changes in the future, but it would be good to have now so we can jump straight into any chapter's doc from the tracker rather than two clicks.

One other wishlist item is to sync the author/reviewer/analyst fields somehow, either copying their names, showing their avatars, or just counting how many there are. This is helpful so we know which chapters are in need of staffing. This is nice-to-have and we could iterate on this in a future PR.

[ibnesayeed]

One other wishlist item is to sync the author/reviewer/analyst fields somehow, either copying their names, showing their avatars, or just counting how many there are. This is helpful so we know which chapters are in need of staffing. This is nice-to-have and we could iterate on this in a future PR.

The format of these issue bodies is not very suitable for a meaningful parsing, but I put together a rather brittle mechanism to parse these nonetheless. While I could have added avatars of members, it will make the process more complicated than we might want, so I simply report number of members in the three teams separated by forward slashes (e.g., 2/3/1 means 2 authors, 3 reviewers, and 1 analyst). This approach is concise and serves the purpose.

[ibnesayeed]

I accidentally closed the progress reporting issue #989 and reopened (and moved from TODO to In progress). #Oops!