GitHub Issues Migration is coming soon

blurb/Changelog and What’s New in Python 3.11 currently uses bpo numbers. The Python 3.11 changelog and What’s New already contains many references to bpo. IMO it’s fine to keep them.

But. After the flag day, what number should I put in the “issue” field of blurb? The GitHub issue number? How will blurb distinguish bpo issues from GH issues?

1 Like

Labels are discussed here: Map bpo issue metadata to GitHub fields/labels · Issue #5 · psf/gh-migration · GitHub

I tried to keep the ones that seemed most used/useful, also based on some analysis of the current issues. The more labels there are the more selecting and applying all the right labels become difficult (as you mentioned about the version), so I’m trying to make things simpler and find a balance between simplicity and accurate classification.

Other things to consider while selecting labels:

  • GitHub doesn’t allow nested labels or label groups so all the labels are listed together, possibly creating a very long list of labels to pick from in the sidebar. Colors and prefixes help, but this also results in a more “chaotic” issue list, with several long and colorful tags.
  • Only triagers/committers can set labels – I don’t think that people reporting issues can. On one hand this is bad because triagers/committers will be responsible for all labels, on the other hand it prevents other people that are not familiar with our conventions from mistriaging issues.
  • GitHub projects or meta-issues could be used to track and organize related issues too.

I initially put those there mostly for debug purposes and also to preserve fields that are not being migrated, so I didn’t spent much time trying to make this more readable, but it’s something we could do. In particular, several of the fields list internal bpo ids, and the corresponding value is also displayed (e.g. actor_id vs actor). All the fields with ids that have been translated could be removed. The first list with the GitHub fields can also be removed.

I’m currently moving more fields (nosy list members, linked PRs, attachments, dependencies, etc.) in the table at the top, so that they they also work as links. Instead of an ini-like code block, I could turn the other values into a table too.

1 Like

Regarding the :issue: issue, I confirm things mentioned by the previous posters:

  • We are planning to add a redirect URL on bpo that given a bpo id it redirects to the corresponding GH issue automatically. URLs pointing to bpo, can be update to this new URL without having to update/know the new GH ID.
  • The code of the :issue: role can be updated easily, to change both the URL and the text.
  • It’s also true that GH uses a shared namespace for issues and PRs, so a new :gh: role makes sense.

The only thing I’m conflicted about is what to do with :issue:. I don’t think it should work with both sets of IDs given the overlapping, and having a :gh: and :bpo: pair makes the most sense to me since it avoids confusion and ambiguity, even though it would also require an s/:issue:/:bpo:/g.

:bpo: could be added as a new explicit role and :issue: kept around as a deprecated alias of :bpo:, even though if we are not going to need bpo links in the future, having :bpo: without the mass-replace is a bit useless since it will never be used. Regardless, in the future we will only use :gh: and make patchcheck (or its modern incarnation if it’s still around) could warn users that try to use :issue: in new code.

1 Like

I’m not too familiar with blurb, but ISTM that it already uses unambiguous bpo-prefixed IDs in the filenames. After the migration I would assume that we will only use GH IDs, so blurb might need to be updated to accept GH IDs and use gh-prefixed IDs instead, possibly pointing the old bpo references to the redirect link mentioned above.

Edit: I reported this here: Update blurb to use GitHub IDs · Issue #428 · python/core-workflow · GitHub

I think the versions are very important, enough that GitHub should add something for them if they haven’t yet. You want to know what users are looking at when they describe a bug.

It’s true that this field is not always populated correctly, but many times it is and it provides useful information.

4 Likes

The problems I see with a version label are:

  • The users can’t set labels anyway, so if they report it, they would have to do it in the message (an issue template might help here). Even if they do, they generally just report the version they are using, and while useful, it doesn’t tell us if other versions are affected (and if you only see e.g. 3.9, does it mean that 3.9 is the only affected version, or the only version tested?).
  • As new releases come out, the version labels need to be updated, new versions added and old versions removed (both on the label list and on all the issues). Given this dynamic nature, it’s difficult to trust the labels (does this issue list only 3.9 and 3.10 because 3.11 is not affected or because no one added the 3.11 label when 3.11 came out?).
  • IME triagers just update the issue with all maintained versions, with a few exceptions (the issue is related to a newly-introduced feature, or the issue has been fixed already). This is generally a fair assumption, but it’s not supported by evidence unless the triagers try to reproduce the issue on different versions (and we can’t expect every triager to do that).

IOW, version labels are often too unreliable and outdated to be trusted. Ideally, once there is a test to reproduce the issue, it should be ran against all maintained versions, either by a GitHub action or by whoever is fixing the issue. This will provide up-to-date and reliable info about the versions that can be trusted, and can be reflected by the already existing needs-backport-to-* PR labels. Perhaps the GitHub action could even use this information to assign and update those label automatically.

FWIW, back in the HG days I used to have ~4 local clones with different Python versions, and I would apply the patch – that usually included test + fix – on all branches, revert the fix, run the test, and if it was failing I would reapply the whole patch on that branch too. While doing this I mostly ignored the version label.

Do you have any specific example/situation in mind? Would it be enough if the versions were mentioned in a comment, where the author could clearly state if they verified/tested, or if they are just assuming?

3 Likes

Yes, issue templates would allow regular users to set labels, for example via a dropdown:

  - type: dropdown
    id: version
    attributes:
      label: Version
      description: What version of our software are you running?
      options:
        - 1.0.2 (Default)
        - 1.0.3 (Edge)

4 Likes

I was aware about the existence of templates, but didn’t know that now they also supported dropdowns and similar – thanks for sharing this! The ones I saw required users to enter information and labels as plain text in the right place and were very error prone. I also heard negative feedback about the usefulness of templates from other developers and maintainers (e.g. some users completely ignored them and wrote their report at the top or bottom, others deleted the template, others filled them in in the wrong way, etc.). For these reasons I was skeptical and wanted to avoid them, but I will now review my decision.

I think they allow entering of data in the report text from a list of values, but they don’t allow setting of actual labels (the ones you can search with via “label:xxx”), do they? Having said that, a github action could probably look for the selections from a dropdown in the issue body, and use them to set labels appropriately.

If triagers would do that then the version would indeed become useless. I’m not aware of this being the case.

Example: I closed issues like ‘I got a compiler error on version 3.4.’ In 2022 it’s fair to ask the OP to create a new issue if they can reproduce it on 3.9+ (and nobody has AFAIK).

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!