GitHub Issues Migration is coming soon

Rather than version tags, I’d prefer “should backport to maintenance releases” and “should backport to security releases” tags (with appropriately shorter names). These don’t go out of date and are actionable - potentially even automatable.

“Reported in version …” data is also useful, but probably only in the text of the report (i.e. through a bug template). Chances are that simply searching for version-like strings will find things well enough, and filtering by creation date also narrows down out-of-date reports, especially if we’re actively getting reporters to repro on latest versions when they report.

6 Likes

I agree that the “reported in version x.y” is a very important information! and it’s fine to have it as text in the first message.

4 Likes

An update on the timeline of this work has been posted:

1 Like

Lifecycle of a Pull Request page of the draft devguide still contains a requirement to create a BPO issue:

Here is a quick overview of how you can contribute to CPython:

  1. Create an issue that describes your change

After migration is done, will we need to create a GitHub issue for each PR?

Actually, PRs and issues share the same tagging, notifications and total summary field, so I believe issues can be left for multi-PR epics, user reports, and questions.

I think we should keep the existing policy, where issues are required for all but the most trivial changes. This helps focus the discussion: issue discussion is about whether we should change some behavior at all, PR discussion about the exact proposed behavior.

7 Likes

So an issue thread is for an idea and a PR thread is about precise implementation that happens to implement this idea in full or in part, right?

I think it should be expressed in the “Create an issue…” line to prevent potential questions like “If I must to associate an issue, what should I write there?” and carbon copying of PR explainers.

1 Like

More-or-less, correct. The PR is for discussing the proposed code. But implementation details can still be discussed on the issue if one is trying to figure out how best to implement something.

5 Likes

In response to a question by @Jelle on python/peps#2484@ambv, can you confirm that the existing BPO links will not automatically turn into redirects and per-message linking will still work? That’s my understanding, but I couldn’t find where it was explicitly stated in either your above OP. PEP 588 (the migration plan) or the updated devguide.

Sidenote—speaking of the later, the link above is only to the top-level preview, and I couldn’t immediately spot the changed content scrolling through the (rather long and seemingly arbitrarily organized) sidebar; after several searches I found the issue tracking (tracker2) page, but it wasn’t immediately obvious to me that the referenced “new FAQ section” was in fact the sub-page titled “Github [sic] issues for BPO users” such that I thought I’d missed it; I had to dig through the PR to confirm that was actually it.

I’m not sure if this experience is enough to motivate any potential changes to the organization to expose it more, or is more specific to this particular context, but at the very least you should consider linking it (or at least the top-level issues page) in the preview link, rather than just the top level of the dev guide. Thanks!

I can confirm this: bpo will continue to work in read-only mode, and links to either bpo issues or messages will work as well. Issues will also include a link that will point to the corresponding GitHub issue, but there is no plan about adding links to individual messages from bpo to GH. bpo will also offer automatic redirects through a different URL.

Note that PEP-588 was initially proposed in 2019, but it’s currently outdated. The actual plans for the migration can be found at GitHub migration · GitHub and Migration and risk management plans · Issue #13 · psf/gh-migration · GitHub. I’m planning to convert this into an informational PEP once I complete the migration so that it can supersede PEP-588 (though I’m not sure about the details of the process).

1 Like

Thanks; that was as I gathered from here.

As an advisory note, per PEP 1 and informal consensus among us PEP editors and SC members is that its better to keep PEPs focused on being change proposals rather than documentation or living specifications, and once a change is implemented, mark it as Final (with any implementation updates as needed/desired) and then add/update the canonical documentation somewhere else more appropriate, like the devguide in this case. You could also add a note at the top briefly mentioning the current status and linking to the canonical documentation, if appropriate for the PEP.

3 Likes

I don’t think that is true for informational PEPs in general. Those are meant to provide “information”, not document change, and if that information changes, so can the PEPs. Of course, for larger overhauls of the content, a new PEP is the better approach.

2 Likes

Apologies is this has been covered, but I didn’t see it mentioned in the migration guide.

Has any thought been given to applying the Experts Index to the CODEOWNERS file for auto-nosy with regards to PRs? My understanding of that file is that for PRs that have a changed file matching a pattern listed in CODEOWNERS, the associated @-mention(s) will be notified about that PR. Much in the same way as nosy-list changes on BPO, just file-based instead of label-based. I know PR != issue, but they are intertwined.

Just a though, as I have been data mining open PRs and noticed a bit of a gap in that area.

My understanding is that CODEOWNERS was rebuilt from scratch, and people have been adding themselves manually to the file. Updating the CODEOWNERS file from the expert index file is an option, however some of the names in experts.rst are not up to date and doing it from scratch ensures that CODEOWNERS only lists people that are active and still interested in being notified.

Note that the python/* repos now support label subscription, which can be used in a way that is similar to the auto-nosy. This works for both PRs and issues, unlike the CODEOWNERS file that only works for PRs (see Set up autonosy on labels · Issue #16 · psf/gh-migration · GitHub).

Finally, the expert index still contains bpo usernames, but I created a PR to update it to GitHub ids a few days ago: Use GitHub usernames in the expert index. by ezio-melotti · Pull Request #825 · python/devguide · GitHub

One important difference between auto-nosy and CODEOWNERS:

Code owners are automatically requested for review when someone opens a pull request that modifies code that they own.

Which is more than a nosy ping.

2 Likes

It might be worth notifying those listed directly in the Experts Index to the existence of CODEOWNERS as a recent thread on python-dev surfaced that there are core developers unaware of it.

Label subscription maps nicely to the interests tables in the Index, but it the stdlib table does seem to match to CODEOWNERS in spirit. Being requested for review does not mean required and would have the same effect as auto-nosy. Although each developer may have their own meaning attached.

Its my understanding that a triager would have, in a perfect world, gone through and added the interested developer(s) to the PR. I see both @-mentions (nosy) and “requested review from” (CODEOWNERS) on the PRs. Not having write access, I do not know which is easier for a triager.

At any rate, the more automation that can be applied here, the better as, in reality, there is never enough eyes to keep up with the influx of new issues/PRs.

I certainly didn’t know it was something I was expected to update manually. And I’m a little concerned about getting the match pattern right given the comments here that some of the existing lines are wrong :slightly_smiling_face:

@-mentions requires actually making a comment on the PR with the mentions, which pings everyone subscribed in addition to the person mentioned, increases clutter, and is somewhat more effort, whereas simply requesting review is quicker, only pings the people requested and doesn’t add an extra comment (though if the triager wants to actually say something, that’s less of an issue). The UI and sorting is a little nicer and more tailored on GitHub’s end for the reviewer.

Of course, the great majority of experts index entries are for specific modules, which map directly to files/dirs in CODEOWNERS and thus could be easily automated without requiring manual triager effort to look up and tag the expert(s). But there certainly are still cases, like cross cutting themes and special circumstnaces, where manual triage is still helpful. On the other hand, it does mean they are tagged as soon as users mark the PR “ready for review”, rather than after an initial review by a traiger, so it could somewhat increase the number of pings experts get in some cases.

Yes.

Correct.

The key thing to understand is those two lists are in separate repos. Probably the closest you could come is some GHA that tries to open a PR on the other repo when the key file has been opened.

Or we can eliminate experts.rst and point people at CODEOWNERS. When I first added CODEOWNERS I think that idea was shot down due to some people not wanting to be tagged on reviews or not all groups tying into code cleanly, but it would simplify things.

Instead of eliminating one or the other, or letting them continue to duplicate one another, I’d suggest focusing each on their respective unique strengths.

CODEOWNERS is a machine- and mostly-human readable means of listing the developers and maintainers of each specific module and sub-componet of the code and automating a number of triage processes and exposing that in the UI. The detailed listing of those, which comprises most of the line length of the current Experts Index, can be transferred there, for those core devs who are active and want to continue to share that responsibility, and exposed both through automation, reading at least mostly human-parsable file for those really interested, and potentially, if there’s sufficient interest, through an autogenerated document (given the simple and consistent source format, and GitHub now offering full support for automatic validation and specific feedback on it).

Meanwhile, the remaining experts index could focus more specifically on the experts and core devs interested in the larger, cross-cutting and higher-level areas of focus, rather than getting bogged down with the maintainers of every module, which is likely more generally useful for interested contributors who want higher-level guidance on a contribution, as opposed to a detailed issue or PR review of an implementation (which would be handled by the automation above). Of course, it would still link to either the CODEOWNERS or a more human-focused file generated from it.

It might be possible to edit the first message to add mentions, similarly to what bedevere does when adding a link to the bpo issue, however I’m not 100% sure that works. I think edited lines and re-evaluated and should trigger @mention notifications, but they won’t send emails to other subscribers. This is a bit tricky to test since it requires multiple accounts and it’s also affected by the “watch” settings and other things. There is also no way to see the list of subscribers afaik.

To summarize the last few posts:

  • the CODEOWNERS file:
    • only works for PRs (not issues)
    • automatically add people as reviewers
    • people have to add themselves to the file
  • label-subscriptions:
    • work for both PRs and issues
    • subscribe the user automatically
    • people have to follow existing labels
  • @mentions:
    • work for both PRs and issues
    • someone (bot or human) has to @mention
    • add some extra clutter

In Add github usernames to the experts index · Issue #507 · python/devguide · GitHub it was proposed to store information in a JSON file that can be used to generate multiple files, possibly in separate repos.
We already have lists of devs in multiple places, including:

  • The list of core devs and their info in a file in python/voters, updated manually
  • The developers.csv file in python/devguide, generated from the voters list
  • The Developer Log in the devguide, generated from the csv
  • The Experts Index in the devguide, updated manually
  • The nosy list autocomplete on bpo (not for long), generated from the experts index (also available through an API)
  • The CODEOWNERS file, updated manually

Also note that the Experts Index has five sections:

IOW, the CODEOWNERS file could replace the stdlib section (and the section could be removed from the expert index), but not the other sections. For the other sections, the only ways to automate subscriptions are:

  • Create even more labels people can subscribe to
  • Create GitHub teams and @mention the team
  • Have triagers directly @mention experts from the list

Note that in all cases we would have to rely on triagers to either add the right labels, or mentioning the teams/users. In addition, labels also allow external people to follow certain issues, whereas teams and direct mentions don’t. The downside is that the more labels there are, the more difficult the triaging becomes.

2 Likes