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.
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.
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.
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).
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.
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.
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
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.
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
@-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.
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:
- only works for PRs (not issues)
- automatically add people as reviewers
- people have to add themselves to the file
- work for both PRs and issues
- subscribe the user automatically
- people have to follow existing labels
- 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
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)
CODEOWNERSfile, updated manually
Also note that the Experts Index has five sections:
- Stdlib: can be mapped to
CODEOWNERSand some labels
- Tools: only has 2 tools, one has a label (
- Platforms: has 7 (used) platforms, only two labels (
- Miscellaneous: ~40 entries, only ~6 labels
- Documentation Translations: 8 entries, no matching labels
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.
As we’re preparing a similar move for https://sagemath.org, see #30363 (Meta-ticket: Migration from Trac to GitHub Issues/PRs) – Sage, I wonder how did you deal with the need to impersonale GitHub users opening issues and writing comments in your procedure.
I see that “Author” account names on bugs.python. org (I’m mangling the rest of the links here, as I’m not allowed more that 2 per post) are mapped to GitHub account names (whenever avaialble?), e.g. on
(Author) rhettinger is mapped to (GitHub account) rhettinger on
I don’t see how to do this without e.g. GitHub access tokens for the GitHub
accounts you want to link. Did you use GitHub’s help here, not some standard tools?
The migration was done with GitHub’s help. When the issues were imported the comments were owned by “mannequin” users with the same usernames as BPO. For members of the Python org on GitHub, the mannequin is associated with their account and becomes indistinguishable from other actions taken by that user. For everybody else it stays as a mannequin.
See this thread for more detail: Map bpo users to GitHub users · Issue #11 · psf/gh-migration · GitHub. You might find some of the other threads in that repo useful for your migration as well.
We worked with GitHub and used their Enterprise Cloud Importer to migrate data from
bugs.python.org to GitHub Issues. This allowed us to map bpo users to their GitHub accounts, but only if they belonged to the
python organization on GitHub (so only core devs could be mapped).
Recently the Twisted folks have also migrated from Trac to GitHub using standard tools. You might find Story: Perform Twisted ticket migration · Issue #16 · chevah/trac-to-github · GitHub useful.
Thanks, yes, we’re also taking the route via Importer - first debugging it on a trial copy of GitHub Enterprise Server. Hopefully we’ll be done in February.