v8.2.0: Release Plan

[AndreasBackx]

This release follows and is worked on together with the 8.1.8 Release Plan.

This summarises the work still needing to be done for 8.2.0, particularly on the PRs and issues attached to the milestone. The summary is based on the comments and additionally some of my own thoughts. This is an attempt to make the 8.2.0 changes easier to review as there has been a lack of time by contributors. This was following a brief discussion on Discord where I asked what can be done to help contribute even though there is a lack of time by the contributors themselves:

Coming up with a list of “here’s bug fixes PRs that work, merge the and make a fix release” could be helpful as well

Pull Requests & Issues

• Python Enum support for click.Choice #605 could be resolved by either
  • Add EnumChoice parameter type #2210
    • Document EnumChoice
    • I propose we leave the aliasing functionality out of the implementation for now. It can be added and discussed in a separate issue.
  • Expand Choice token normalization + make generic #2796
• Mark parameter as deprecated #2263
  • Introduce Parameter.deprecated + Command.deprecated message customization #2271
    • Better title: add deprecated to Option.
    • This does not add deprecated to Parameter so it is not available to @click.argument.
    • Align deprecation implementation between it and Command(deprecated: bool) implementation.
    • Make it print a deprecated messaged on use.
  • Move deprecated to Parameter so both Option and Argument support it.
• Fix metavar for Choice options when show_choices=False #2365
  • It's ignoring a type error that might be preventable if param.param_type_name == "option" were to be replaced with isinstance(param, Option). However, that will introduce a circular dependency. I'm not sure it's something that's easily fixable right now.
• Give a UserWarning when Parameter is overriden by name #2397
  • The current implementation checks every single time an option is used, whether its name has been used before. I feel like we can move this check elsewhere so it only does this check once per command. If you want to be technical about it, it should make the check O(n) instead of O(n^2) where n is the number of options.
    • Move duplicate option declaration check so it only runs once per command instead of once per option.
  • Document that a UserWarning will be logged if an "option" declaration is reused.
  • Nit: the warnings import should be moved to the module level.
• Show empty default #2501 can simply be closed because it was fixing Empty string default values are not displayed #2500 which was resolved by Fix printing of default option value to handle empty strings #2724.
• Hide default value when show_default is False #2509
  • Already reviewed and ready to go, waiting to be merged.
• Split generation of help extra items and rendering #2517
  • Document Option.get_help_extra Let's not make it entirely public for now.
  • I'm personally not the biggest fan of the untyped implementation. I think it should be typed so it's clear what "extra items" are supported.
    • Revamp implementation of get_help_extra to add typing instead of relying on untyped dict.
• Keep track of <stderr> and <stdout> mix in CliRunner results #2523
  • Good to go, seems agreed upon.
• show env var in error hint #2696
  • Good to go.
• Fix closing of callbacks on CLI exit #2680
  • Well tested as well.
  • Perhaps the ctx.call_on_close documentation should mention the change in behaviour as well? Though I would say it's assumed that an exit actually would call this too and it's not needed.
• Add functionality to hide the progress bar Issue #2609 #2727
  • Before this PR ProgressBar.is_hidden existed. This adds ProgressBar.hidden which is the value of the new passed constructor field hidden. This was mentioned in the comments as well but then the author faced issues getting it to work in tests. I'm sure we can get this to work however, if not, then we can at least document why it's there.
    • Merge ProgressBar._is_hidden and ProgressBar.hidden into ProgressBar.is_hidden.

Potentially Included

These are primarily added in this separate section as I classified them as 8.2.0 though haven't necessarily been "agreed upon" by others (yet).

• Added functionality to set flag_value correctly when using envvar #2788 flags enabled with envvar will return the flag_value if set.
• Improve echo_via_pager behaviour in face of errors #2775
  • Seems good to go, I don't think we should update the utilities documentation for this as they seem like implementation details that shouldn't matter?
• Add file-like pager: click.get_pager_file() #1572 might be made easier if rebased on Improve echo_via_pager behaviour in face of errors #2775. I said they can rebase on Improve echo_via_pager behaviour in face of errors #2775 and already start any work as we're aiming to get Improve echo_via_pager behaviour in face of errors #2775 in 8.2.0.
• Draft: add python_version to version_option available message formats #2681
  • Needs checklist completion (tests, changes, etc.)
• Make click.Context generic over obj #2663
• feat: new method for choice fail #2622
  • Needs checklist completion (tests, changes, etc.)
• Help shown via no_args_is_help results in exit code 2, was 0 #1489
  • Might need a documentation change.
• Adds support for editing multiple files #2068
  • Needed some changes to keep filename and not introduce filenames.
• ensure context __exit__ is called during shell completion #2767
  • Fixed in Close contexts created during shell completion #2644. #2800
• specialize progressbar(length=...) as ProgressBar[int] #2630

Next steps

I propose the following:

1. A contributor with the necessary power to merge all of these PRs into either main or another temporary branch, the latter being preferred imo.
2. I will follow up and address all of the openstanding issues highlighted above. Each will be done in a PR and can be commented on further there.
3. Once the openstanding (and other issues that arose during their "fixing") are merged, 8.2.0 can be released.
   • Almost all of these PRs have a good amount of tests that should prevent any low hanging issues from rearing their heads.

This assumes we do not add any more items to 8.2.0 so we can keep it manageable for now.

Let me know if this sounds like a good idea. I'm also available on Discord.

[kdeldycke]

I just tried to use the main branch to test the upcoming 8.2.0 release, but it seems that my PR #2811 , while present in 8.1.8 (see: 70c673d), has not been merged into main.

Should I consider main as not being a follow-up on 8.1.8?

[kdeldycke]

Looking at the different branches, it seems that the last time stable was merged into main is Nov 5, 2024 (see: d791537). All changed in stable from Nov 5, 2024 to today have not reached the main branch yet.

There was an attempt in #2830 but it has not been updated since Dec 24, 2024, and so lacks changes both from stable and main that were pushed after the 8.1.8 release.

Is there a plan to reconcile stable and main so I can test the upcoming 8.2.0 before its release?

[kdeldycke]

So all in all, what's missing in main is this changeset: 26aa7bf...stable

[kdeldycke]

I finally fixed all conflicts in #2873. This should help the release of 8.2.0.

[webknjaz]

Might be worth including a fix for #2877.