PEP 588: Update GitHub Issues Migration Plan

[ezio-melotti]

PEP-0588 was written together with PEP-0581 and outlined a migration plan. Since then, several things changed and https://github.com/psf/gh-migration/projects/1 was created and updated to track the migration. Then, closer to the migration date, I wrote psf/gh-migration#13.

I discussed with the SC both the possibility of creating a new PR or updating PEP-0581, and IIRC they were leaning towards the latter, however it will need to be pretty much rewritten. Given that the migration is going to happen soon, the rewrite (or new pep) could serve the following purposes:

• Clarify that PEP-0581 doesn't reflect the actual plan used for the migration if a new pep is written, or update it with up-to-date info;
• Offer some background about the problems and the decisions taken (linking to relevant GH issues/discussions), including issue numbering, label mapping, user subscriptions, etc.;
• Document the actual process followed during the migration and all the changes that were involved (this is the bulk of Migration and risk management plans psf/gh-migration#13);

IOW, it will mostly be an informational PEP to document the migration.

What do you think?

(CC @Mariatta)

[warsaw]

Clarify that PEP-0581 doesn't reflect the actual plan used for the migration if a new pep is written, or update it with up-to-date info;

Or just write a new PEP and make 581 Superseded-By it

[CAM-Gerlach]

PEP 581 seems to just be a rationale for GitHub over BPO, rather than a description of the migration plan, which is in PEP 588. I can imagine some of the points changing somewhat in light of the experience implementing it, but I'm not sure the former needs a bottom to top rewrite, since it documents the rationale at the time of the decision.

As for PEP 588, playing devil's advocate here, but now that the change is on the eve of being implemented, if updating the current PEP isn't feasible (which would generally be preferable), is a new PEP really the right place for this, or is there another more better venue? @encukou , thoughts?

[encukou]

PEP 588 is a change proposal, so IMO it is the right place. Documentation about how devs should use/migrate to GH should go to devguide, but that's already the plan.
Only having the info in psf/gh-migration#13, and updating PEP 588 to point there, would also be OK as far as I'm concerned. Bu if there's more in-depth discussion/rationale to be added, a PEP seems better.

[Mariatta]

At the docs WG meeting today, the group agrees that PEP 588 is the right place to document the migration process, and that we should not create yet another PEP.

[hugovk]

Two years later: do we still need to update PEP 588 beyond changing the status from Draft? Who can do it?

[willingc]

@hugovk @warsaw @Mariatta Since this was an informational PEP when going from bpo to github and outlined potential options, what do you recommend for the next step other than Draft?

[hugovk]

I suggest we don't spend a lot of time on the text. The PEP described the plan at one point in time. The migration is complete, and things inevitably changed during the process.

I don't think there's much value in updating the PEP to fully document what the plan actually was in the end: it's documented in psf/gh-migration#13, we're not going to repeat BPO->GH, and if another project is planning something similar, other things will have changed in the past few years for them to consider. They can still review the various PEPs and psf/gh-migration#13.

@encukou said:

Only having the info in psf/gh-migration#13, and updating PEP 588 to point there, would also be OK as far as I'm concerned.

This sounds good. Let's point the PEP to psf/gh-migration#13 and update the status?