Document Qiskit versioning and stability policy

[mtreinish]

This commit adds a new document to the hosted documentation for Qiskit's versioning and stability policy. This is a continuation of Qiskit/qiskit#11205 which documents for Qiskit users the versioning and stability policy for the library. It includes an explanation of how to interpret version numbers, the tentative release schedule for the project, as well as a definition of what interfaces are considered stable. This outlines the minimum support windows for major versions and how deprecations and breaking changes will work with regards to versioning. This documentation is critical to include with the Qiskit 1.0.0 release as it establishes the expectations around the major version release for users (all previous documentation on the subject tactically avoided the discussion of a major version).

[mtreinish]

This was generated via the following python script:

import pandas as pd
import plotly.express as px

data = [
    ["0.44.0", "2023-07-27", "2023-11-03", "0.x"],
    ["0.45.0", "2023-11-03", "2024-01-18", "0.x"],
    ["0.46.0", "2024-01-18", "2024-08-15", "0.x"],
    ["1.0.0", "2024-01-31", "2024-05-17", "1.x"],
    ["1.1.0", "2024-05-17", "2024-08-15", "1.x"],
    ["1.2.0", "2024-08-15", "2024-11-21", "1.x"],
    ["1.3.0", "2024-11-21", "2025-02-06", "1.x"],
    ["1.4.0", "2025-02-06", "2025-08-28", "1.x"],
    ["2.0.0", "2025-02-20", "2025-05-29", "2.x"],
    ["2.1.0", "2025-05-29", "2025-08-28", "2.x"],
    ["2.2.0", "2025-08-28", "2025-11-27", "2.x"],
]
release_schedule = pd.DataFrame(
    data, columns=["Release", "Release Date", "End of Support", "Major version"]
)
fig = px.timeline(release_schedule, x_start="Release Date", x_end="End of Support", y="Release", color="Major version", title="Tentative Qiskit Release Schedule")
fig.update_yaxes(autorange="reversed")

Plotly is a javascript library under the covers and generates a web interactive version of this plot (you can zoom in and hover over the releases to get more details) we should be to embed this more natively into the documentation in the future. For example, I just used the plotly api to generate a minified js version of the plot embedded in a standalone html file here: https://gist.githubusercontent.com/mtreinish/18cde5e482b5315b1b2fb09f048276a6/raw/f1a399be8d12ded44f49ecae4295844d48392162/gistfile1.txt

But in the interest of time I just opted to use a static png file for this first commit.

[Eric-Arellano]

Thank you!

[javabster]

We discussed with the docs team earlier today where the best place to put this info would be. There's no clear "best place" to put it and after dec we want to think more carefully about where content like this should ideally go. In the meantime these are the other "good enough" options we can think about:

1. add this page inside the Advanced setup dropdown in Start
2. add this page inside the Install dropdown in Start
3. instead of a whole page take the words in this PR and put it in the existing qiskit install page, underneath the operating system support section.

@mtreinish I'm happy with either of these 3 options, but is there one that would prefer?

[mtreinish]

If you don't think it'll make the install page too long, I'll go with number 3. It is really just extra information about installing and having an extra page for this felt a bit much.

[Eric-Arellano]

If you don't think it'll make the install page too long

We were thinking of using <details> so that the advanced information on that page (e.g. platform support) is expandable and closed by default, #369, like this:

documentation/docs/support.mdx

Lines 39 to 45 in 53de645

	<details>
	<summary>
	How do I cite Qiskit in my research?
	</summary>
	Please cite Qiskit by using the included [BibTeX file](https://github.com/Qiskit/qiskit/blob/main/CITATION.bib).
	</details>

It might be helpful to use this mechanism in your PR, too. You'd keep the headers the same as top-level, but could put certain details in the details.

[mtreinish]

I've updated this to be in the install guide. If there needs to be any changes to the formatting please feel free to just push it to the PR branch

[1ucian0]

Maybe "experimental APIs" need it's own subsection as their exceptionality might be important to set the expectations on breaking changes during stable cycles.

[mtreinish]

TBH, I didn't want to call it out too much as I think it's an anti-pattern we wouldn't want to use widely. I just wanted to make sure we document it as something that we can do if needed. I'm not sure we should make it a specific subsection.

[1ucian0]

I think a "Qiskit as a dependency" can be its own section, to give more relevance and detail (for example, downstream using a feature introduced in a minor should use ~=.)

[kevinhartman]

Can you clarify what this means to document this? Does it include deprecation warning logic?

[mtreinish]

I just meant something like the prelude in the release notes will say something like "0.46.4 is the final release for the major version 0.x and there will be no further release for the 0.x release series."

[javabster]

The only significant feedback I have on this is that can we please put each subheading into a </details> component like the sections above? This is quite a lengthy page and we're trying to prevent users feeling overwhelmed

[mtreinish]

I added the details section in: f7ff76c feel free to just push to this branch if I did it incorrectly.

[javabster]

LGTM 🚀 thanks for the contribution!