Prepare release notes for Qiskit Terra 0.19 #7329

jakelishman · 2021-11-30T22:57:45Z

Summary

The main object of this PR is to move the release notes for 0.19 into a separate folder, and to reformat them into a consistent style with correct formatting and working Sphinx cross-references.

In doing so, I also came across some places with missing documentation, and a couple of places where the Sphinx documentation was being generated twice for quite a few objects, which messed with the ability to cross-reference correctly. This PR is then actually in a few commits, which may be viewed separately to see the changes more easily:

move the release notes into releasenotes/notes/0.19
add objects that were missing from the API docs/module imports completely (that looked like they should have been included - I didn't do it indiscriminately)
updated a couple of deprecation notices that incorrectly said 0.18 due to their milestone getting moved
reorganised the qiskit.pulse documentation to avoid duplicating definitions of all its objects (this could be split into a separate PR)
actually reformatted the release notes

Details and comments

Most of the release notes changes are mechanical - fixing typos, formatting and cross-reference links. In a few cases, there was insufficient context in the release note itself when read in isolation, so those I mostly rewrote. If you want to review the changes only, you may want to filter the diff only to the single commit named "Reformat 0.19 release notes" (its hash may change if I rebase).

The main documentation addition was hooking the approximate quantum compiler into the actual tree. This then necessitated a couple of fixes in its documentation to account for Sphinx errors that had previously gone unnoticed. Adding a few things into the import path created some cyclical imports, so those are moved into runtime imports.

While the changes to the qiskit.pulse documentation look big, in reality, the rendered documentation is almost identical (because it's already good - I didn't want to mess with it!). I just rearranged how it gets generated, and which docstrings are responsible for various parts of it. The main developer-facing change is that now there is only one canonical reference path for every object in the qiskit.pulse namespace. The builder objects, Schedule and ScheduleBlock are in the top-level qiskit.pulse, and most other stuff is in qiskit.pulse.instructions, .library, .transforms, etc (with no further nesting within these). This means that suffix references will now generally work (e.g. :class:`.Gaussian` will now actually resolve, and be equal to :class:`~qiskit.pulse.library.Gaussian`). This should also help users searching for documentation, because there won't be duplication in the results.

This is likely going to be the last PR for 0.19, and the one that gets tagged as the release. On hold til all other PRs are in, at which point I'll rebase it and write a release prelude.

Todo before merge:

merge in remaining 0.19 PRs and move release notes
rewrite QASM 3 and control-flow release notes to reference the builder interface/promote control-flow more

A few objects added in new features for the 0.19 cycle did not get added into higher-level `__init__` files, either as imports or documentation links. This adds several documentation links in, and fixes some cyclic imports that were previously hidden due to the objects not being fully imported.

These deprecation notices were written in a PR that was originally targetted for the 0.18 release but later got shifted to 0.19.

Previously, autosummary documentation files were being generated for most objects in `qiskit.pulse` in two namespaces: `qiskit.pulse` and (e.g.) `qiskit.pulse.library`. In other cases, the module-level documentation was not being generated at all. This moves the responsibility for defining all the definitions into the respective submodules, and turns the `qiskit.pulse` docstring into a series of `.. automodule::` calls. The relevant module docstrings are merged with any content that was already in the `qiskit.pulse` docstring, to ensure that the displayed documentation on the `qiskit.pulse` page is almost identical to what it was before. Various Sphinx crossreferences within the `pulse` module (and referring to it from elsewhere) were previously broken, in part because of the duplication. It should be more reliable when creating crossreferences now. The abstract base classes are also added in `.. autoclass::` calls in suitable locations, since they are a common source of failed Sphinx crossreferences elsewhere. (It's easy to accidentally get the duplication when using `autosummary`. If it does need to be used on more than one page, then only the canonical path should use the `:toctree:` directive. Pulse also had more of this than other places because it's generally a bit more thoroughly documented.)

This reformats the release notes for Terra 0.19, canonicalising the style and ensuring that all Sphinx crossreferences link correctly. In some cases there is no suitable target for documentation (especially in the case of removals), so these are left as simple monospaced font.

coveralls · 2021-11-30T23:32:52Z

Pull Request Test Coverage Report for Build 1545764687

25 of 25 (100.0%) changed or added relevant lines in 18 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+0.001%) to 83.093%

Totals
Change from base Build 1544860931:	0.001%
Covered Lines:	51668
Relevant Lines:	62181

💛 - Coveralls

mtreinish

I just went through the doc changes to start here are some quick comments. I'm gonna take a break before starting the release note meat of this PR to start preparing a fix commit for those 2 broken transpiler passes before we're committed to the API in the release.

docs/apidocs/transpiler_builtin_plugins.rst

qiskit/pulse/__init__.py

qiskit/pulse/instructions/__init__.py

qiskit/transpiler/passes/calibration/builders.py

qiskit/transpiler/passes/optimization/echo_rzx_weyl_decomposition.py

qiskit/circuit/library/arithmetic/exact_reciprocal.py

qiskit/quantum_info/synthesis/xx_decompose/decomposer.py

qiskit/synthesis/evolution/product_formula.py

qiskit/synthesis/evolution/suzuki_trotter.py

jakelishman · 2021-12-01T13:52:07Z

I'm going to leave the changes for now, just to ease the CI - I've got them done locally, but I'll not push til more stuff has merged.

Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

jakelishman · 2021-12-01T13:54:11Z

Well, I was going to leave things, then I accidentally closed the PR rather than just commenting, and re-opening re-triggered the build anyway. So now they're done.

releasenotes/notes/0.19/add-passmanager-config-from-backend-af5dd7d99ec053ef.yaml

releasenotes/notes/0.19/full_prec_sympy-aeee8210091ef20f.yaml

releasenotes/notes/0.19/user-config-mpl-style-a9ae4eb7ce072fcd.yaml

1ucian0 · 2021-12-04T07:31:18Z

I dont thinks is possible to suggest changes in unmodified moved files. So Ill drop them here:

add-backend-v2-ce84c976fb13b038.yaml:33: rest of Qiskit can use today with any backend. Subclasses of the abstract

releasenotes/notes/0.19/remove-schemas-ca9f3f2e0f08bca8.yaml

releasenotes/notes/0.19/taper_empty_operator_fix-53ce20e5d2b68fd6.yaml

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>

jakelishman · 2021-12-06T12:49:04Z

Resolved all Luciano's most recent comments in 1423ebf. The styling issue I think needs fixing in our theme.

mtreinish

Almost done with my final pass (need to step away for a bit right now) so I'll likely have some other comments when I get back

releasenotes/notes/0.19/0.19-prelude-65c295aa9497ed48.yaml

...otes/notes/0.19/QuantumCircuit.decompose-takes-which-gate-to-decompose-d857da5d0c41fb66.yaml

releasenotes/notes/0.19/SPSA-termination-callback-a1ec14892f553982.yaml

releasenotes/notes/0.19/add-detach-prefix-088e96b88ba29927.yaml

releasenotes/notes/0.19/add-pulse-gate-pass-dc347177ed541bcc.yaml

mtreinish · 2021-12-06T12:53:34Z

releasenotes/notes/0.19/add-pulse-gate-pass-dc347177ed541bcc.yaml

+    Along with this change, a schedule was added to
+    :class:`~qiskit.pulse.InstructionScheduleMap` and is implicitly updated with
+    a metadata ``"publisher"``.  Backend-calibrated gate schedules have a
+    special publisher kind to avoid overriding circuits with calibrations of
+    already known schedules.  Usually, end-users don't need to take care of this
+    metadata as it is applied automatically.  You can call
+    :meth:`.InstructionScheduleMap.has_custom_gate` to check if the map has
+    custom gate calibration.


Which change?

@nkanazawa1989

I had a bit of a rewrite in a40c877, but I may have got some of that not 100% correct. Would be good if someone with more knowledge could check.

releasenotes/notes/0.19/add-pulse-gate-pass-dc347177ed541bcc.yaml

releasenotes/notes/0.19/added-multiformat-support-b5d3c7c7c1536951.yaml

releasenotes/notes/0.19/draw-statevector-in-ket-notation-0726959d1f6ea3ce.yaml

mtreinish

We can remove gate-type-hints-b287215190144ceb.yaml it's not really a useful release note and if we did want to document it should be a new feature and not an upgrade note as it's not breaking anyone.

I still need to go through the fix notes, but they're not as important so we can ship it as is if needed.

releasenotes/notes/0.19/readout-mitigation-classes-2ef175e232d791ae.yaml

releasenotes/notes/0.19/7274-6f57628a7995a461.yaml

releasenotes/notes/0.19/sparse-pauli-internal-8226b4f57a61b982.yaml

releasenotes/notes/0.19/symengine-bump-20dedd5204870e7a.yaml

...otes/notes/0.19/QuantumCircuit.decompose-takes-which-gate-to-decompose-d857da5d0c41fb66.yaml

releasenotes/notes/0.19/dag_node_to_op_in_out_node-af2cf9c3e7686285.yaml

mtreinish

I quickly skimmed through the fix notes and caught a few small things but for the most part it looked okay. I think once the issues I commented on before and these are fixed we should be good to go on this.

releasenotes/notes/0.19/fix-configurable-fake-backend-6a07ca5a6159baf5.yaml

releasenotes/notes/0.19/fix-transpile-empty-list-c93a41d4145a01c3.yaml

mtreinish · 2021-12-06T14:58:58Z

I've removed the on hold here because all the release PRs are merged. Once we're done with the release notes this is ready to merge and we can tag the release.

Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

jakelishman · 2021-12-06T16:34:25Z

All changes now addressed (including removing the gate type hints note). I rewrote the PulseGate note a little bit (conversation still unresolved above), so it'd be good for someone with more knowledge to check that.

mtreinish

LGTM, it looks like you addressed all the comments thanks for the quick turnaround.

For the pulse gate release note if it's not clear we can always update it after the release. I think at this point it's good enough in it's current form.

This was made in order to simplify some import paths, but as a side effect it caused ten `QuantumCircuit`s to be created on import of `qiskit`, which spoiled the QPY backwards compatibility tests and likely had import performance implications. The import of this likely should not need to create circuits, but for now, we revert its import rather than making a change this close to release.

jakelishman added 5 commits November 30, 2021 22:50

Move 0.19 release notes into subdirectory

6661347

Update incorrect deprecation notice

a810af8

These deprecation notices were written in a PR that was originally targetted for the 0.18 release but later got shifted to 0.19.

jakelishman added on hold Can not fix yet documentation Something is not clear or an error documentation priority: high labels Nov 30, 2021

jakelishman added this to the 0.19 milestone Nov 30, 2021

jakelishman added this to To do in Documentation via automation Nov 30, 2021

jakelishman requested review from chriseclectic, DanPuzzuoli, eggerdj, lcapelluto, nkanazawa1989, nonhermitian, taalexander and a team as code owners November 30, 2021 22:57

mtreinish reviewed Dec 1, 2021

View reviewed changes

Cryoris reviewed Dec 1, 2021

View reviewed changes

jakelishman closed this Dec 1, 2021

Documentation automation moved this from To do to Done Dec 1, 2021

jakelishman reopened this Dec 1, 2021

jakelishman and others added 3 commits December 1, 2021 13:53

Fix typo

5c898b5

Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

Clarify ExactReciprocal documentation

aa157bc

Merge remote-tracking branch 'ibm/main' into fix/release-notes-0.19

61775a9

Fix docs warning

abc11e1

1ucian0 reviewed Dec 4, 2021

View reviewed changes

releasenotes/notes/0.19/add-passmanager-config-from-backend-af5dd7d99ec053ef.yaml Outdated Show resolved Hide resolved

1ucian0 reviewed Dec 4, 2021

View reviewed changes

releasenotes/notes/0.19/full_prec_sympy-aeee8210091ef20f.yaml Outdated Show resolved Hide resolved

releasenotes/notes/0.19/user-config-mpl-style-a9ae4eb7ce072fcd.yaml Outdated Show resolved Hide resolved

1ucian0 reviewed Dec 4, 2021

View reviewed changes

releasenotes/notes/0.19/remove-schemas-ca9f3f2e0f08bca8.yaml Outdated Show resolved Hide resolved

1ucian0 reviewed Dec 4, 2021

View reviewed changes

releasenotes/notes/0.19/taper_empty_operator_fix-53ce20e5d2b68fd6.yaml Outdated Show resolved Hide resolved

jakelishman and others added 3 commits December 6, 2021 10:14

Updates from Luciano

1423ebf

Co-authored-by: Luciano Bello <bel@zurich.ibm.com>

Merge remote-tracking branch 'ibm/main' into fix/release-notes-0.19

baabcec

Update BasisTranslator release note

8beb883

Add an invisible code block

afd0ce6

mtreinish reviewed Dec 6, 2021

View reviewed changes

releasenotes/notes/0.19/fix-configurable-fake-backend-6a07ca5a6159baf5.yaml Outdated Show resolved Hide resolved

releasenotes/notes/0.19/fix-transpile-empty-list-c93a41d4145a01c3.yaml Outdated Show resolved Hide resolved

mtreinish removed the on hold Can not fix yet label Dec 6, 2021

jakelishman and others added 4 commits December 6, 2021 15:57

Rewrite PulseGate pass release note

a40c877

Update release notes

33ffd86

Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

Merge remote-tracking branch 'ibm/main' into fix/release-notes-0.19

b1ca250

Remove note about type hints

153396f

mtreinish mentioned this pull request Dec 6, 2021

Disable approximate synthesis based on device gate error. #7348

Closed

Fix PulseGate typos

925a9c3

mtreinish previously approved these changes Dec 6, 2021

View reviewed changes

mtreinish added automerge Changelog: None Do not include in changelog labels Dec 6, 2021

jakelishman dismissed mtreinish’s stale review via bb6f3a9 December 6, 2021 17:16

mtreinish approved these changes Dec 6, 2021

View reviewed changes

mergify bot merged commit d5094ee into Qiskit:main Dec 6, 2021

jakelishman deleted the fix/release-notes-0.19 branch December 6, 2021 21:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Prepare release notes for Qiskit Terra 0.19 #7329

Prepare release notes for Qiskit Terra 0.19 #7329

jakelishman commented Nov 30, 2021 •

edited by mtreinish

Loading

coveralls commented Nov 30, 2021 •

edited

Loading

mtreinish left a comment

jakelishman commented Dec 1, 2021

jakelishman commented Dec 1, 2021

1ucian0 commented Dec 4, 2021

jakelishman commented Dec 6, 2021

mtreinish left a comment

mtreinish Dec 6, 2021

eggerdj Dec 6, 2021

jakelishman Dec 6, 2021

mtreinish left a comment

mtreinish left a comment

mtreinish commented Dec 6, 2021 •

edited

Loading

jakelishman commented Dec 6, 2021

mtreinish left a comment

Prepare release notes for Qiskit Terra 0.19 #7329

Prepare release notes for Qiskit Terra 0.19 #7329

Conversation

jakelishman commented Nov 30, 2021 • edited by mtreinish Loading

Summary

Details and comments

coveralls commented Nov 30, 2021 • edited Loading

Pull Request Test Coverage Report for Build 1545764687

💛 - Coveralls

mtreinish left a comment

Choose a reason for hiding this comment

jakelishman commented Dec 1, 2021

jakelishman commented Dec 1, 2021

1ucian0 commented Dec 4, 2021

jakelishman commented Dec 6, 2021

mtreinish left a comment

Choose a reason for hiding this comment

mtreinish Dec 6, 2021

Choose a reason for hiding this comment

eggerdj Dec 6, 2021

Choose a reason for hiding this comment

jakelishman Dec 6, 2021

Choose a reason for hiding this comment

mtreinish left a comment

Choose a reason for hiding this comment

mtreinish left a comment

Choose a reason for hiding this comment

mtreinish commented Dec 6, 2021 • edited Loading

jakelishman commented Dec 6, 2021

mtreinish left a comment

Choose a reason for hiding this comment

jakelishman commented Nov 30, 2021 •

edited by mtreinish

Loading

coveralls commented Nov 30, 2021 •

edited

Loading

mtreinish commented Dec 6, 2021 •

edited

Loading