search

betterscientificsoftware / bssw.io

Better Scientific Software Homepage
https://bssw.io
Other
140 stars 90 forks source link

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

Open bartlettroscoe opened 4 months ago

bartlettroscoe commented 4 months ago

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:

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

image

This issue is to track the transition from the old

Tasks

bernhold commented 4 months ago

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 commented 4 months ago

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

Sorry, did not realize that #2060 existed.

bartlettroscoe commented 4 months ago

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

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

image

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 commented 4 months ago

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:

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:

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 commented 4 months ago

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:

image

Here is the automation for the "Backlog" column:

image

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

image

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

image

Here is the automation for the "Done" column:

image

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

bartlettroscoe commented 4 months ago

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

and it shows:

image

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:

image

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

image

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

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

image

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:

image

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

image

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

image

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 commented 4 months ago

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

The project board currently looks like right now:

image

Here is the "Idea Backlog" automation:

image

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:

image

Here is the "Ready to publish" automation:

image

Here is the "Ready for digest" automation:

image

Here is the "Done" automation:

image

bartlettroscoe commented 4 months ago

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

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

(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:

?

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 commented 4 months ago

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 commented 4 months ago

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:

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 commented 4 months ago

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

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

bartlettroscoe commented 4 months ago

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

bartlettroscoe commented 4 months ago

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

showing:

image

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)

image

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

image

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

image

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

image

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 commented 4 months ago

@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 commented 4 months ago

@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 commented 4 months ago

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 commented 2 months ago

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

bernhold commented 2 months ago

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.