version_added field in configuration option doesn't work correctly in providers documentation

[Taragolis]

Apache Airflow version

2.7.0

What happened

Initial finding: #33960 (comment)

Since Airflow 2.7.0 we have an ability to store configuration options in providers, everything works fine, except field version_added.

The logic around this field expect Airflow version and not Provider version. Any attempt to add in this field any value greater than current version of Airflow (2.7.0 at that moment) will result that configuration option won't rendered in documentation, seem like it not prevented to add this configuration at least airflow config get-value command return expected option.

What you think should happen instead

Various, depend on final solution and decision.

Option 1:
In case if we would not like use this field for providers we might ignore this field in providers configurations.
For Community Providers we could always set it to ~

Option 2:
Dynamically resolve depend on what a source of this configuration, Core/Provider

Option 3:
Add provider_version_added and use for show in which version of provider this configuration added
We could keep version_added if configuration option in provider related to Airflow Version

Option 4:
Suggest you own 😺

How to reproduce

Create configuration option with version_added greater than current version of Airflow, for stable it is 2.7.0 for dev 2.8.0

config:
  aws:
    description: This section contains settings for Amazon Web Services (AWS) integration.
    options:
      session_factory:
        description: |
          Full import path to the class which implements a custom session factory for
          ``boto3.session.Session``. For more details please have a look at
          :ref:`howto/connection:aws:session-factory`.
        default: ~
        example: my_company.aws.MyCustomSessionFactory
        type: string
        version_added: 3.1.1

Operating System

n/a

Versions of Apache Airflow Providers

n/a

Deployment

Other

Deployment details

No response

Anything else

No response

Are you willing to submit PR?

• Yes I am willing to submit a PR!

Code of Conduct

• I agree to follow this project's Code of Conduct

[eladkal]

I raised it in
#32604 (comment)

[potiuk]

I believed (at least ) It's been fixed.

[potiuk]

Version added should be "provider_version" when it was added and I was almost 100% sure it's been fixed and that you can put any version there - maybe it's slipped somehow ?

[Taragolis]

I check that only IMAP set value greater than 2.7/2.8

airflow/airflow/providers/imap/provider.yaml

Lines 68 to 89 in c077d19

	config:
	imap:
	description: "Options for IMAP provider."
	options:
	ssl_context:
	description: |
	ssl context to use when using SMTP and IMAP SSL connections. By default, the context is "default"
	which sets it to ``ssl.create_default_context()`` which provides the right balance between
	compatibility and security, it however requires that certificates in your operating system are
	updated and that SMTP/IMAP servers of yours have valid certificates that have corresponding public
	keys installed on your machines. You can switch it to "none" if you want to disable checking
	of the certificates, but it is not recommended as it allows MITM (man-in-the-middle) attacks
	if your infrastructure is not sufficiently secured. It should only be set temporarily while you
	are fixing your certificate configuration. This can be typically done by upgrading to newer
	version of the operating system you run Airflow components on,by upgrading/refreshing proper
	certificates in the OS or by updating certificates for your mail servers.
	If you do not set this option explicitly, it will use Airflow "email.ssl_context" configuration,
	but if this configuration is not present, it will use "default" value.
	type: string
	version_added: 3.3.0
	example: "default"
	default: ~

As result this option not presented into the doc:
https://airflow.apache.org/docs/apache-airflow-providers-imap/stable/configurations-ref.html

I'm not sure for 100% but seems like it might only affect documentation. Because configs generated without any problem

[potiuk]

Yes. I think I fixed "generation" but documentation might be wrong.

[potiuk]

Fix in #34011

[potiuk]