Transition BSSw.io GitHub Issue boards from Projects Classic to new Projects implementation before 8/32/2024

[bartlettroscoe]

CC: @betterscientificsoftware/bssw-editorial-board

Description

It seems that GitHub support for the old Projects Classic Issue boards is ending. For example, on 6/13/2024 the page:

• https://github.com/betterscientificsoftware/bssw.io/projects/3

is showing that support is ending "August 23, 2024" showing:

This issue is to track the transition from the old

Tasks

• Transition the "BSSw Internal" board first and see what happens and what the issues are
• Inform @betterscientificsoftware/bssw-editorial-board about this transition
• Transition the "Content Development" board

[bernhold]

This is a dupe of #2060, but I can close that one.

The automatic migration has worked fine for me for other boards. But any action that touches project boards will need to be revisited. On the other hand, gh (the CLI) now has an extension for V2 projects, so it is not hard to write actions to manipulate the board. I've done this for the HPC-BP webinar series to orchestrate the generation of a whole bunch of issues and adding them to the project board with all of the desired properties.

[bartlettroscoe]

This is a dupe of #2060, but I can close that one.

Sorry, did not realize that #2060 existed.

[bartlettroscoe]

As a first experiment, I will transition the TriBITS project boards:

• https://github.com/TriBITSPub/TriBITS/projects/1
• https://github.com/TriBITSPub/TriBITS/projects/2

When you click "Start Migration", you get the dialog:

NOTE: That suggests that automation will NOT be migrated. Therefore, we will need to carefully note the automation before the migration and then manually set up the same automation.

[bartlettroscoe]

I just learned an interesting tidbit while transitioning the TriBITSPub/TriBITS projects. If you want to maintain the project board IDs, you need to them in order. I did not do that and I transitioned the classic project/2 first which become the new project/1 and then I transitioned the classic project/1 which become the new project/2. In other words:

• "TriBITS": https://github.com/TriBITSPub/TriBITS/projects/2 => https://github.com/orgs/TriBITSPub/projects/1
• "TriBITS Refactor": https://github.com/TriBITSPub/TriBITS/projects/1 => https://github.com/orgs/TriBITSPub/projects/2

That is not the worst thing in world, the project "TriBITS" is meant to be the permeant project board while "TriBITS Refactor" was meant to be temporary during the big TriBITS refactor (which is basically done and therefore that board should likely go away).

But given that the existing classic boards are:

• "BSSw Internal": https://github.com/betterscientificsoftware/bssw.io/projects/2
• "Content Development": https://github.com/betterscientificsoftware/bssw.io/projects/3,

we would transition "BSSw Internal" first which will become the new board projects/1 and then transitioning "Content Development" next would make the new board projects/2.

So, I will go ahead and transition "BSSw Internal" first and carefully log my work and the checks.

[bartlettroscoe]

Before doing the migration of the "BSSw Internal" board, I will capture the existing structure and automations so we have something to compare against.

Where is what the board currently looks like:

Here is the automation for the "Backlog" column:

Here is the automation for the "Selected for development" column (there is none):

Here is the automation for the "In progress" column:

Here is the automation for the "Done" column:

These look like pretty standard automations but I will make sure they are maintained after the migration.

[bartlettroscoe]

I finished the initial transition of the board "BSSw Internal" and now it is at the page:

• https://github.com/orgs/betterscientificsoftware/projects/4/views/1

and it shows:

I also changed the name of the view from "View 1" to "Board" which shows up in the name of the tab.

Comparing to the screenshot before the transition above, one can see that the same number of issues are shown as well as the same ordering of issues at the top, the same note for the "Selected for development" column, etc. Note that the issues are formatted differently with the new board not showing who created the issue.

The new project board shows both an expanded pop-up view for an issue issue like:

and a compressed pop-up issue view for an issue (clicking the 📌icon) like:

Now for the automation. I had to enable some of the automations.

For example, I enabled the "Item added to project" automation:

This only adds new issues to the "Backlog" column. There is no way to set up a different automation to set PRs to "In progress" like the old board. (This is a feature regression w.r.t. the old board implementation.)

I then set the "item reopened" workflow step:

The "Item closed" automation was already set and enabled:

The "Pull request merged" automation was also already set:

These new project automation functionality has very little flexibility. With just a little bit of work, they could of allowed more than one automation for "Item added to project" or "Item reopened" to do different things for Issues vs. PRs. Very disappointed :-(

[bartlettroscoe]

Now let me capture the setup for the existing "Content development" classic board:

• https://github.com/orgs/betterscientificsoftware/projects/4/views/1

The project board currently looks like right now:

---

Here is the "Idea Backlog" automation:

---

There is no "Topic Review" automation.

---

There is no "Ready to write" automation.

---

There is no "In progress" automation.

---

Here is the "Item review" automation:

---

Here is the "Ready to publish" automation:

---

Here is the "Ready for digest" automation:

---

Here is the "Done" automation:

[bartlettroscoe]

@bernhold, @rinkug, @betterscientificsoftware/bssw-editorial-board,

I finished the migration of the "BSSw Internal" board:

• https://github.com/orgs/betterscientificsoftware/projects/4/views/1

(see above) and I have documented the "Content Development" board and its automations above.

Any objections to me pulling the trigger and doing the migration of the "Content Development" board:

• https://github.com/betterscientificsoftware/bssw.io/projects/3

?

NOTE: Given what I learned above, we may not be able to match all of the automations but we can do the best we can.

Let me know. (I would like to pull the trigger on this sooner rather than later while this is fresh in my mind.)

[bernhold]

Thanks for your work on this @bartlettroscoe! I think we can use actions to implement the workflows where the builtins are inadequate. I can help with this, but not immediately, so we may need to operate manually for a bit.

I'm good with you going ahead with the Content board.

[bartlettroscoe]

I think we can use actions to implement the workflows where the builtins are inadequate. I can help with this, but not immediately, so we may need to operate manually for a bit.

Right! That is what GitHub intended for more flexibility:

• https://docs.github.com/en/actions/managing-issues-and-pull-requests/using-github-actions-for-project-management

I'm good with you going ahead with the Content board.

Okay, I will pull the trigger on that and document the current state of the workflows and the gaps.

[bartlettroscoe]

NOTE: Here is info on workflows for the new GitHub project board:

• https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects
• https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions

And it looks like there are some standard GHA for automating project board workflows in the GHA marketplace:

• https://github.com/marketplace/actions/github-project-automation

[bartlettroscoe]

Starting the migration of "Content Development" board now ...

[bartlettroscoe]

I did the migration of the board "Content Development" which is now at:

• https://github.com/orgs/betterscientificsoftware/projects/5/views/1

showing:

I set the name to "Board". Below I describe the automations that I set to match and those that could not be matched with the built-in automation for the new GH Project boards. Compare these automations to the old project board shown above.

---

A) Workflows transitions set up to match the old board automations

These workflow transitions were supported by the new GH Project built-in workflows.

---

A.1) "Idea Backlog" automation => "Item added to the project" (New issues added to "Ideal backlog" column)

---

A.2) "Read to publish" automation => "Code review approved" (PR approved moves PR to "In progress" column)

---

A.3) "Ready for digest" automation => "Pull request merged" (PR merged moved to "Ready for digest" column)

---

A.4) "Done" automation => "Item closed" (Issue and PR closed moved to "Done" column)

---

B) Workflow automations that do not match old board automations

These workflows will need to be automated using GHA.

---

B.1) "Item review" automation => NONE ("Pending approval by reviewer" PR added to "Item review" column)

---

Summary

So it looks like the only project workflow that I could not get to match with the old project board implementation is the "Item review" automation shown above. Personally, I don't know if that is worth the effort to automate. In my opinion, when the author of a PR thinks the PR is ready to review, they should manually add the reviewer and move the PR or Issue into "Item review"

[bartlettroscoe]

@betterscientificsoftware/bssw-editorial-board

I created a new column for the new "BSSw Internal" board called "In review" and I added this Issue that that column.

I think this is ready to be reviewed by someone else and closed if it looks good. (I don't think any more automations are needed but we can add some later in a new issue using GHA.)

[markcmiller86]

@bartlettroscoe I read through all your notes here. Thanks for detailed notes! I was wondeering about the descriptive text that appears at the top of most columns explaining why items in the column are supposed to be there (e.g. the criteria).

Now, it looks like that description box no longer supports markdown. It is just a basic text box. So, it looks like you added some sticky issues (my wording) at the top of each column with links to the description text.

In today's meeting, we considered moving all that text into the column's Description box but reformatting it so it "looks decent" there. But, I am now wondering...what are your thoughts about this?

At the very least, I would like to adjust the existing sticky issues to just a short title such as "Column Description" which links to the description text.

[bernhold]

On other boards I've converted, I've used the concept of "draft items" on the project board itself to replace the old note cards. These draft items are a V2 feature. They're not issues -- they live only on the board -- though there is a mechanism to convert them into issues (which I've never used). They seem to happily stay at the top of columns (which is something that issues don't do, and was also a perennial problem with the note cards on the classic boards.

If you click the Add item button at the bottom of a column, you'll create a draft item by detail -- you have to do more work to create anything else.

[bartlettroscoe]

I think this is done, yes? Can we close this issue?

[bernhold]

I haven't yet had time to write the actions to put things on the boards, in the right columns and such.

I don't care whether you want to keep this open or create a new issue specifically for this task.