Skip to content
This repository has been archived by the owner on Aug 19, 2023. It is now read-only.

Remove metapackage-specific parts of documentation #1788

Merged
merged 1 commit into from
Aug 4, 2023

Conversation

jakelishman
Copy link
Member

@jakelishman jakelishman commented Aug 4, 2023

Summary

This removes many sections of the documentation that refer to the metapackage as a whole, the elements of the metapackage, or refer to Terra as Terra. This is intended to be in line with the new branding decisions around the Qiskit project.

With the current community management structure still a little up in the air, we are (at least temporarily) removing the repository-decision flowchart from the documentation, since this documentation will primarily be for Qiskit Terra. The contributor flowchart, or something similar, may end up on the landing pages of the Ecosystem documentation, or another community hub.

Details and comments

I've left references to "Terra" in place, because those should still logically be removed as part of the general migration in naming within the Terra repository. I've also left the build processes in place that git clone Terra and the tutorials; we need those to continue having a working docs build in this repo. They'll get modified as these files get merge to Terra as well, but they need to stay alive here.

One of the notable removals is the API docs links to Aer and IBMQ from the main page, since as of the deployed metapackage version (0.44), those are no longer part of the metapackage.

Fix #1787.
Fix #1778 - mostly; the version logic is way stripped down, and will now automatically work on Terra at least as much as we need when the files are merged.
Fix #1667
Fix #1643

This removes many sections of the documentation that refer to the
metapackage as a whole, the elements of the metapackage, or refer to
Terra as Terra.  This is intended to be in line with the new branding
decisions around the Qiskit project.

With the current community management structure still a little up in the
air, we are (at least temporarily) removing the repository-decision
flowchart from the documentation, since this documentation will
primarily be for Qiskit Terra.  The contributor flowchart, or something
similar, may end up on the landing pages of the Ecosystem documentation,
or another community hub.
Comment on lines -22 to -33

.. _decide-what-to-work-on:

************************
Decide What to Work on
************************

If you're not sure what type of contribution is right for you, take a look at the following flowchart to help you:

.. raw:: html
:file: images/contributor-flowchart.svg

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I spoke with @javabster, and the current recommendation is that we remove this (and the flowchart image), with the intention / hope that it finds a new place on the Ecosystem contributing guide, or something like that.

Comment on lines +81 to +101
def add_versions_to_config(_app, config):
"""Add a list of old documentation versions that should have links generated to them into the
context, so the theme can use them to generate a sidebar."""
# First 0.x version where Qiskit/Terra and the metapackage aligned on number.
first_unified_zero_minor = 45

# Start with the hardcoded versions of the documentation that were managed while the metapackage
# still existed, so are based on tags that don't exist in the Qiskit package repo.
versions = ["0.19"] + [f"0.{x}" for x in range(24, first_unified_zero_minor)]

proc = subprocess.run(["git", "describe", "--abbrev=0"], capture_output=True, check=True)
current_version = proc.stdout.decode("utf8")
current_version_info = current_version.split(".")
if current_version_info[0] != "0":
raise Exception("TODO: handle major versions")
versions.extend(
f"0.{x}" % x for x in range(first_unified_zero_minor, int(current_version_info[1]) + 1)
)
config.html_context["version_list"] = versions


Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a simplified and modified version of the logic that finds the old versions of deployed docs that will work with both the metapackage repo and Terra once moved. On the Terra side we'll probably need to modify this again in fairly short order anyway, especially around major versions, but for now, it'll work.

The previous versionutils.py version also populated a version_label field into the HTML context that hasn't been used for a while (only used in an older, unused version of the layout.html template), so I removed it.

Comment on lines 96 to -102

When installing the elements and components from source, by default their
``development`` version (which corresponds to the ``master`` git branch) will
be used, as opposed to the ``stable`` version (which contains the same codebase
as the published ``pip`` packages). Since the ``development`` versions of an
element or component usually include new features and changes, they generally
require using the ``development`` version of the rest of the items as well.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've removed all the instructions about installing Aer because it's no longer relevant to the metapackage/Terra - they should live in Aer's documentation instead. I also flattened this structure down to avoid needing the raw HTML headers that didn't work with Sphinx cross-refs and caused a couple of broken links.

Comment on lines -82 to -88

.. toctree::
:caption: Other API References
:hidden:

Qiskit Aer <https://qiskit.org/ecosystem/aer>
Qiskit IBM Quantum Provider (deprecated) <https://qiskit.org/ecosystem/ibmq-provider>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are gone now because Aer and IBMQ are no longer in the metapackage.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file just generated a useless empty HTML page that wasn't even linked from anywhere.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heh, it did say it was orphaned :)

Copy link
Member Author

@jakelishman jakelishman Aug 4, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tbf it'd have failed the build if it weren't marked as orphaned

.. math:: |\psi\rangle = \left(|00\rangle+|11\rangle\right)/\sqrt{2}.
.. math:: \lvert\psi\rangle = \left(\lvert00\rangle+\lvert11\rangle\right)/\sqrt{2}.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The | broke the syntax highlighting in my editor so I couldn't read anything properly lol.

Comment on lines -38 to -74
Backporting procedure:
----------------------

When backporting a patch from master to stable, we want to keep a
reference to the change on master. When you create the branch for the
stable PR, use::

$ git cherry-pick -x $master_commit_id

However, this only works for small self-contained patches from master.
If you need to backport a subset of a larger commit (from a squashed PR,
for example) from master, do this manually. In these cases, add::

Backported from: #master pr number

so that we can track the source of the change subset, even if
a strict cherry-pick doesn\'t make sense.

If the patch you're proposing will not cherry-pick cleanly, you can help
by resolving the conflicts yourself and proposing the resulting patch.
Please keep Conflicts lines in the commit message to help review of the
stable patch.



Backport labels
---------------

Bugs or PRs tagged with ``stable backport potential`` are bugs
that apply to the stable release too and may be suitable for
backporting once a fix lands in master. Once the backport has been
proposed, the tag should be removed.

Include ``[Stable]`` in the title of the PR against the stable branch,
as a sign that setting the target branch as stable was not
a mistake. Also, reference to the PR number in master that you are
porting.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is long since out-of-date - I replaced it with correct, up-to-date text.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, I do still follow this in the rare situations where we can't use mergify to backport.

Comment on lines -76 to -109
.. _versioning_strategy:

*****************
Qiskit Versioning
*****************

The Qiskit project is made up of several elements each performing different
functionality. Each is independently useful and can be used on their own,
but for convenience we provide this repository and meta-package to provide
a single entrypoint to install all the elements at once. This is to simplify
the install process and provide a unified interface to end users. However,
because each Qiskit element has its own releases and versions, some care is
needed when dealing with versions between the different repositories. This
document outlines the guidelines for dealing with versions and releases of
both Qiskit elements and the meta-package.

For the rest of this guide the standard Semantic Versioning nomenclature will
be used of: ``Major.Minor.Patch`` to refer to the different components of a
version number. For example, if the version number was ``0.7.1``, then the major
version is ``0``, the minor version ``7``, and the patch version ``1``.


Meta-package Version
====================

The Qiskit meta-package version is an independent value that is determined by
the releases of each of the elements being tracked. Each time we push a release
to a tracked component (or add an element) the meta-package requirements, and
version will need to be updated and a new release published. The timing should
be coordinated with the release of elements to ensure that the meta-package
releases track with element releases.

Adding New Tracked Elements
---------------------------
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All the stuff about metapackage versioning is removed as no longer relevant, since there's only one component now, and the old version relationships can just be read off a table. The information about how the number was bumped was relevant when the metapackage was being updated, but is no longer needed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think post migration we should document that we're following semver along with the stability guidelines.

Comment on lines -10 to +112
Qiskit Metapackage Version qiskit-terra qiskit-aer qiskit-ignis qiskit-ibmq-provider qiskit-aqua Release Date
========================== ============ ========== ============ ==================== =========== ============
0.44.0 0.25.0 2023-07-27
0.43.3 0.24.2 0.12.2 0.20.2 2023-07-19
0.43.2 0.24.1 0.12.1 0.20.2 2023-06-28
0.43.1 0.24.1 0.12.0 0.20.2 2023-06-02
0.43.0 0.24.0 0.12.0 0.20.2 2023-05-04
0.42.1 0.23.3 0.12.0 0.20.2 2023-03-21
0.42.0 0.23.2 0.12.0 0.20.2 2023-03-10
0.41.1 0.23.2 0.11.2 0.20.1 2023-02-23
0.41.0 0.23.1 0.11.2 0.20.0 2023-01-31
0.40.0 0.23.0 0.11.2 0.19.2 2023-01-26
0.39.5 0.22.4 0.11.2 0.19.2 2023-01-17
0.39.4 0.22.3 0.11.2 0.19.2 2022-12-08
0.39.3 0.22.3 0.11.1 0.19.2 2022-11-25
0.39.2 0.22.2 0.11.1 0.19.2 2022-11-03
0.39.1 0.22.1 0.11.1 0.19.2 2022-11-02
0.39.0 0.22.0 0.11.0 0.19.2 2022-10-13
0.38.0 0.21.2 0.11.0 0.19.2 2022-09-14
0.37.2 0.21.2 0.10.4 0.19.2 2022-08-23
0.37.1 0.21.1 0.10.4 0.19.2 2022-07-28
0.37.0 0.21.0 0.10.4 0.19.2 2022-06-30
0.36.2 0.20.2 0.10.4 0.7.1 0.19.1 2022-05-18
0.36.1 0.20.1 0.10.4 0.7.0 0.19.1 2022-04-21
0.36.0 0.20.0 0.10.4 0.7.0 0.19.0 2022-04-06
0.35.0 0.20.0 0.10.3 0.7.0 0.18.3 2022-03-31
0.34.2 0.19.2 0.10.3 0.7.0 0.18.3 2022-02-09
0.34.1 0.19.1 0.10.2 0.7.0 0.18.3 2022-01-05
0.34.0 0.19.1 0.10.1 0.7.0 0.18.3 2021-12-20
0.33.1 0.19.1 0.9.1 0.7.0 0.18.2 2021-12-10
0.33.0 0.19.0 0.9.1 0.7.0 0.18.1 2021-12-06
0.32.1 0.18.3 0.9.1 0.6.0 0.18.1 0.9.5 2021-11-22
0.32.0 0.18.3 0.9.1 0.6.0 0.18.0 0.9.5 2021-11-10
0.31.0 0.18.3 0.9.1 0.6.0 0.17.0 0.9.5 2021-10-12
0.30.1 0.18.3 0.9.0 0.6.0 0.16.0 0.9.5 2021-09-29
0.30.0 0.18.2 0.9.0 0.6.0 0.16.0 0.9.5 2021-09-16
0.29.1 0.18.2 0.8.2 0.6.0 0.16.0 0.9.5 2021-09-10
0.29.0 0.18.1 0.8.2 0.6.0 0.16.0 0.9.4 2021-08-02
0.28.0 0.18.0 0.8.2 0.6.0 0.15.0 0.9.4 2021-07-13
0.27.0 0.17.4 0.8.2 0.6.0 0.14.0 0.9.2 2021-06-15
0.26.2 0.17.4 0.8.2 0.6.0 0.13.1 0.9.1 2021-05-19
0.26.1 0.17.4 0.8.2 0.6.0 0.13.1 0.9.1 2021-05-18
0.26.0 0.17.3 0.8.2 0.6.0 0.13.1 0.9.1 2021-05-11
0.25.4 0.17.2 0.8.2 0.6.0 0.12.3 0.9.1 2021-05-05
0.25.3 0.17.1 0.8.2 0.6.0 0.12.3 0.9.1 2021-04-29
0.25.2 0.17.1 0.8.1 0.6.0 0.12.3 0.9.1 2021-04-21
0.25.1 0.17.1 0.8.1 0.6.0 0.12.2 0.9.1 2021-04-15
0.25.0 0.17.0 0.8.0 0.6.0 0.12.2 0.9.0 2021-04-02
0.24.1 0.16.4 0.7.6 0.5.2 0.12.2 0.8.2 2021-03-24
0.24.0 0.16.4 0.7.6 0.5.2 0.12.1 0.8.2 2021-03-04
0.23.6 0.16.4 0.7.5 0.5.2 0.11.1 0.8.2 2021-02-18
0.23.5 0.16.4 0.7.4 0.5.2 0.11.1 0.8.2 2021-02-08
0.23.4 0.16.3 0.7.3 0.5.1 0.11.1 0.8.1 2021-01-28
0.23.3 0.16.2 0.7.3 0.5.1 0.11.1 0.8.1 2021-01-26
0.23.2 0.16.1 0.7.2 0.5.1 0.11.1 0.8.1 2020-12-15
0.23.1 0.16.1 0.7.1 0.5.1 0.11.1 0.8.1 2020-11-12
0.23.0 0.16.0 0.7.0 0.5.0 0.11.0 0.8.0 2020-10-16
0.22.0 0.15.2 0.6.1 0.4.0 0.10.0 0.7.5 2020-10-05
0.21.0 0.15.2 0.6.1 0.4.0 0.9.0 0.7.5 2020-09-16
0.20.1 0.15.2 0.6.1 0.4.0 0.8.0 0.7.5 2020-09-08
0.20.0 0.15.1 0.6.1 0.4.0 0.8.0 0.7.5 2020-08-10
0.19.6 0.14.2 0.5.2 0.3.3 0.7.2 0.7.3 2020-06-25
0.19.5 0.14.2 0.5.2 0.3.2 0.7.2 0.7.3 2020-06-19
0.19.4 0.14.2 0.5.2 0.3.0 0.7.2 0.7.2 2020-06-16
0.19.3 0.14.1 0.5.2 0.3.0 0.7.2 0.7.1 2020-06-02
0.19.2 0.14.1 0.5.1 0.3.0 0.7.1 0.7.1 2020-05-14
0.19.1 0.14.1 0.5.1 0.3.0 0.7.0 0.7.0 2020-05-01
0.19.0 0.14.0 0.5.1 0.3.0 0.7.0 0.7.0 2020-04-30
0.18.3 0.13.0 0.5.1 0.3.0 0.6.1 0.6.6 2020-04-24
0.18.2 0.13.0 0.5.0 0.3.0 0.6.1 0.6.6 2020-04-23
0.18.1 0.13.0 0.5.0 0.3.0 0.6.0 0.6.6 2020-04-20
0.18.0 0.13.0 0.5.0 0.3.0 0.6.0 0.6.5 2020-04-09
0.17.0 0.12.0 0.4.1 0.2.0 0.6.0 0.6.5 2020-04-01
0.16.2 0.12.0 0.4.1 0.2.0 0.5.0 0.6.5 2020-03-20
0.16.1 0.12.0 0.4.1 0.2.0 0.5.0 0.6.4 2020-03-05
0.16.0 0.12.0 0.4.0 0.2.0 0.5.0 0.6.4 2020-02-27
0.15.0 0.12.0 0.4.0 0.2.0 0.4.6 0.6.4 2020-02-06
0.14.1 0.11.1 0.3.4 0.2.0 0.4.5 0.6.2 2020-01-07
0.14.0 0.11.0 0.3.4 0.2.0 0.4.4 0.6.1 2019-12-10
0.13.0 0.10.0 0.3.2 0.2.0 0.3.3 0.6.1 2019-10-17
0.12.2 0.9.1 0.3.0 0.2.0 0.3.3 0.6.0 2019-10-11
0.12.1 0.9.0 0.3.0 0.2.0 0.3.3 0.6.0 2019-09-30
0.12.0 0.9.0 0.3.0 0.2.0 0.3.2 0.6.0 2019-08-22
0.11.2 0.8.2 0.2.3 0.1.1 0.3.2 0.5.5 2019-08-20
0.11.1 0.8.2 0.2.3 0.1.1 0.3.1 0.5.3 2019-07-24
0.11.0 0.8.2 0.2.3 0.1.1 0.3.0 0.5.2 2019-07-15
0.10.5 0.8.2 0.2.1 0.1.1 0.2.2 0.5.2 2019-06-27
0.10.4 0.8.2 0.2.1 0.1.1 0.2.2 0.5.1 2019-06-17
0.10.3 0.8.1 0.2.1 0.1.1 0.2.2 0.5.1 2019-05-29
0.10.2 0.8.0 0.2.1 0.1.1 0.2.2 0.5.1 2019-05-24
0.10.1 0.8.0 0.2.0 0.1.1 0.2.2 0.5.0 2019-05-07
0.10.0 0.8.0 0.2.0 0.1.1 0.2.1 0.5.0 2019-05-06
0.9.0 0.8.0 0.2.0 0.1.1 0.1.1 0.5.0 2019-05-02
0.8.1 0.7.2 0.1.1 0.1.0 2019-05-01
0.8.0 0.7.1 0.1.1 0.1.0 2019-03-05
0.7.3 >=0.7,<0.8 >=0.1,<0.2 2019-02-19
0.7.2 >=0.7,<0.8 >=0.1,<0.2 2019-01-22
0.7.1 >=0.7,<0.8 >=0.1,<0.2 2019-01-17
0.7.0 >=0.7,<0.8 >=0.1,<0.2 2018-12-14
========================== ============ ========== ============ ==================== =========== ============
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When the documentation is merged to Terra, the old tag-based dynamic table generator would have stopped working because the information wouldn't have been present on Terra. Since this release-notes file will become "legacy releases notes" on Terra, I just froze the table into a static object (can easily be updated manually if we make another metapackage release from this repo), so it'll work in both repos.

Copy link
Member

@mtreinish mtreinish left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, all these changes make sense now that qiskit == qiskit-terra.

current_version = proc.stdout.decode("utf8")
current_version_info = current_version.split(".")
if current_version_info[0] != "0":
raise Exception("TODO: handle major versions")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heh, I'm glad you left this in place. It was one of my favorite parts of this extension.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I upgraded it to an actual exception haha - previously it just silently output nothing.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heh, it did say it was orphaned :)

Comment on lines -76 to -109
.. _versioning_strategy:

*****************
Qiskit Versioning
*****************

The Qiskit project is made up of several elements each performing different
functionality. Each is independently useful and can be used on their own,
but for convenience we provide this repository and meta-package to provide
a single entrypoint to install all the elements at once. This is to simplify
the install process and provide a unified interface to end users. However,
because each Qiskit element has its own releases and versions, some care is
needed when dealing with versions between the different repositories. This
document outlines the guidelines for dealing with versions and releases of
both Qiskit elements and the meta-package.

For the rest of this guide the standard Semantic Versioning nomenclature will
be used of: ``Major.Minor.Patch`` to refer to the different components of a
version number. For example, if the version number was ``0.7.1``, then the major
version is ``0``, the minor version ``7``, and the patch version ``1``.


Meta-package Version
====================

The Qiskit meta-package version is an independent value that is determined by
the releases of each of the elements being tracked. Each time we push a release
to a tracked component (or add an element) the meta-package requirements, and
version will need to be updated and a new release published. The timing should
be coordinated with the release of elements to ensure that the meta-package
releases track with element releases.

Adding New Tracked Elements
---------------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think post migration we should document that we're following semver along with the stability guidelines.

Comment on lines -38 to -74
Backporting procedure:
----------------------

When backporting a patch from master to stable, we want to keep a
reference to the change on master. When you create the branch for the
stable PR, use::

$ git cherry-pick -x $master_commit_id

However, this only works for small self-contained patches from master.
If you need to backport a subset of a larger commit (from a squashed PR,
for example) from master, do this manually. In these cases, add::

Backported from: #master pr number

so that we can track the source of the change subset, even if
a strict cherry-pick doesn\'t make sense.

If the patch you're proposing will not cherry-pick cleanly, you can help
by resolving the conflicts yourself and proposing the resulting patch.
Please keep Conflicts lines in the commit message to help review of the
stable patch.



Backport labels
---------------

Bugs or PRs tagged with ``stable backport potential`` are bugs
that apply to the stable release too and may be suitable for
backporting once a fix lands in master. Once the backport has been
proposed, the tag should be removed.

Include ``[Stable]`` in the title of the PR against the stable branch,
as a sign that setting the target branch as stable was not
a mistake. Also, reference to the PR number in master that you are
porting.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, I do still follow this in the rare situations where we can't use mergify to backport.

@mtreinish mtreinish added the automerge This PR will automatically merge once its CI has passed label Aug 4, 2023
@mergify mergify bot merged commit dfcb2f4 into Qiskit:master Aug 4, 2023
10 checks passed
@jakelishman jakelishman deleted the prep-docs-for-migration branch August 6, 2023 18:07
jakelishman added a commit to jakelishman/qiskit-terra that referenced this pull request Aug 11, 2023
…apackage#1788)

This removes many sections of the documentation that refer to the
metapackage as a whole, the elements of the metapackage, or refer to
Terra as Terra. This is intended to be in line with the new branding
decisions around the Qiskit project.

With the current community management structure still a little up in the
air, we are (at least temporarily) removing the repository-decision
flowchart from the documentation, since this documentation will
primarily be for Qiskit Terra. The contributor flowchart, or something
similar, may end up on the landing pages of the Ecosystem documentation,
or another community hub.


I've left references to "Terra" in place, because those should still
logically be removed as part of the general migration in naming within
the Terra repository. I've also left the build processes in place that
`git clone` Terra and the tutorials; we need those to continue having a
working docs build in this repo. They'll get modified as these files get
merge to Terra as well, but they need to stay alive here.

One of the notable removals is the API docs links to Aer and IBMQ from
the main page, since as of the deployed metapackage version (0.44),
those are no longer part of the metapackage.

Fix Qiskit/qiskit-metapackage#1787.
Fix Qiskit/qiskit-metapackage#1778 - mostly; the version logic is _way_ stripped down, and will
now automatically work on Terra at least as much as we need when the
files are merged.
Fix Qiskit/qiskit-metapackage#1667 
Fix Qiskit/qiskit-metapackage#1643
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
automerge This PR will automatically merge once its CI has passed
Projects
None yet
2 participants