Track Resources ready for next month and next highlight

[rinkug]

Description

How do we keep track of resources that are in pipeline for publishing and potentially ready for digest highlight?

Proposed solution

See below. Summary:

• Use GitHub Milestones (names 2024-01 Digest, 2024-02 Digest, etc.) and assign 2 curated content issues (or a PR instead of an issue).
  • Each article must have clear author that will create the article for the content.
• Create a new "Ready for Digest" column in the Content Development Kanban board for CC article issues and PRs that are complete and published but have not yet been highlighted in a digest.

That will make sure that we are covered for CC articles to appear in the digest each month.

NOTE: Blog articles due each month are already being handled in the blogs planning repo using a similar process

Previous proposed solution from @rinkug

• We discussed milestones (ex: early-feb-2024, late-feb-2024) to be assigned to each issue/PR. This is similar to blog planning board
• We discussed having a generic milestone (ex: due-2024) to track issues that folks are working on but have no date. Alternative to having such a specific label is to just keep that issue in the “in progress” column
• We discussed having “Ready to highlight” column before done. Maybe PRs can go from “Ready to publish” to “Ready to highlight” (right now they go to “done” column, when merged). Challenge: we dont want “all” PRs to go to “Ready to highlight” …some can go “done” (ex: updates to existing article) and so how do we deal with such issues/PRs?

Tasks

• Generate <YYYYY>-<MM> Digest milestones out through 2030 using script (see below)
• Create new column “Ready for Digest” in Content Development board with automation (see below)
• Update CC workflow in the document docs/pages/bssw/bssw_curatedworkflow.md

[bernhold]

I have added milestones to the repo for the digests through the end of 2030.

[bernhold]

Seems to me that we have two basic goals here:

1. Track what has and hasn’t appeared in a digest
2. Provide enough information so that we can be confident that we’ll have the number of articles we want to highlight for each month’s digest

I think (1) could be handled with an addition column on the Content Development board, between Ready to Publish and Done. “Ready for Digest” or something like that. Merged PRs go into that column instead of Done. Some PRs aren’t actually articles (non-article changes, updates to articles, etc.) so we’d probably want to do some filtering. That could obviously be manual, but maybe we could do something based on labels to automate the most obvious cases. When we assemble a digest, we’d take our cues from the Ready for Digest column, and (manually) move the cards to Done. This part doesn’t actually need milestones or anything.

But for (2), I think we need to be able to look across the board and see that we have commitments to produce enough articles to satisfy the monthly quota. I think relevant cards could appear anywhere from the Ready to Write column or further to the right. We could use labels, but then we’d need 12 labels to easily distinguish the targets (though in practice I expect we’ll only have 1-2 of these labels active at a time). Or we could use milestones. They appear on the cards (below the labels), so they’re visible. And you can filter on them, etc. One challenge with labels is that if you have too many, I don’t think they all fit on the card. And in this sense, I think milestones may be better.

So I guess my solution would be a union of the two ideas above: an additional column and milestones.

Do you have other ideas about how to approach this?

[bernhold]

@bartlettroscoe replied

I agree with this approach (which is what we discussed at the meeting today).

[rinkug]

@bernhold : Thanks for outlining and we should go ahead and implememt this as soon as you have time.

[bartlettroscoe]

@bernhold, thanks for copy and pasting your excellent email summarizing the approach for this that you suggested last meeting. I agree 100%. Let's implement this.

As you have already run your script to add all of the milestones out to 2030-12, all we need to do is add the "Ready for Digest" column, adjust the board automation, update some documentation on the review and publishing process, and start following the process.

[bernhold]

I've added a Ready for digest column and adjusted the automations. Merged PRs will go into Ready for digest. Once they go out in a digest, the issues should be moved manually from Ready for digest to Done. Closed issues and PRs closed without merging will go straight to Done, as in the past.

[bernhold]

Note that there will be occasional red herrings in Ready for digest: PRs for updates (rather than new articles) would normally not be highlighted. There may be other red herrings as well. My feeling is that it should not be hard to weed these out manually. But if it becomes problematic, we can probably create an action that recognizes labels that would indicate things that are uninteresting for the digest.

But I propose we close this as done and if we decide we want better automation, we open a new ticket for that. If you object, speak up quickly.

[bartlettroscoe]

@bernhold and @rinkug, is there any documentation about the publication process that needs to be updated for these changes?

[bartlettroscoe]

@bernhold, I am noticing that milestones for past months are still shown at:

• https://github.com/betterscientificsoftware/bssw-blog-planning/milestones?direction=asc&sort=due_date&state=open

like for 2023-08 through 2024-01. (The most current milestone for that project should be 2024-02 Early and 2024-02 Late).

Should we have a policy to close these milestones after they are complete and the BSSw digest goes out? That will make it easy to see the status of upcoming milestones have for upcoming digests.

I think this suggests that we need to document this process somewhere?

[bernhold]

Probably. I don't think we've ever documented anything about the digest per se. Have we documented the kanban board anywhere outside of the board itself?

[bernhold]

@bartlettroscoe there's an action on the blog-planning repo that is supposed to automatically close milestones that are (a) past their deadline and (b) have no open issues. However it hasn't worked in a while and I haven't had/taken the time to try to figure out if there's anything I can do about it or find another action to try.

But I agree, it would be nice to have something to automatically close old milestones.

[bartlettroscoe]

Probably. I don't think we've ever documented anything about the digest per se. Have we documented the kanban board anywhere outside of the board itself?

Yes, I think so:

• https://betterscientificsoftware.github.io/bssw.io/bssw_curatedworkflow.html

That means we need to update the file:

• docs/pages/bssw/bssw_curatedworkflow.md

?

[bartlettroscoe]

But I agree, it would be nice to have something to automatically close old milestones.

@bernhold, yes, but for now it is easy enough to close them manually when we are looking at:

• https://github.com/betterscientificsoftware/bssw.io/milestones

(just one click on "close" per month).

Update: But here is the GHA for automatically closing completed milestones:

• https://github.com/marketplace/actions/close-milestones-that-are-at-100

[bartlettroscoe]

FYI: I updates the issues header above with the current scope, proposed solution and tasks to complete (most of which are complete). The last thing to do is to update the workflow documentation.