Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Handle Qiskit release notes structure correctly to split out the notes by version #359

Closed
Eric-Arellano opened this issue Nov 15, 2023 · 2 comments · Fixed by #537
Closed
Assignees

Comments

@Eric-Arellano
Copy link
Collaborator

Follow up to #294 and #281.

@frankharkins found that it works well using the HTML generation script. A key change from Qiskit itself is we have one page per minor release, like release-notes/0.45. We need to make two improvements:

  1. Restructure Qiskit/qiskit to have one release note file per release for future releases. Whereas right now they have the file release_notes for all notes from Qiskit 0.45 forward
  2. Update our script updateApiDocs.ts to handle new release notes automatically, including the wonkiness of the prior release note files (legacy_release_notes.html).
@Eric-Arellano
Copy link
Collaborator Author

Eric-Arellano commented Dec 5, 2023

I'm thinking that the simplest solution will be for Qiskit to continue having only a single file release_notes.rst. Note that we removed legacy_release_notes.rst already.

Then we have the Qiskit devs configure Reno so that release_notes.rst only has the release notes for the current version of that branch, such as 1.0 vs 1.1. That will simplify updateApiDocs.ts because it only needs to convert release_notes.rst into a single file under the release-notes/ folder for the current API version. That is, it doesn't need logic to parse the file and extract out the relevant version from the file; the file already only has what is relevant.

We need Qiskit devs to be okay with the plan, since they'd need to tweak the versions listed in release_notes.rst with releases. I'll present this plan to them at the weekly meeting next week.

cc @arnaucasau and @frankharkins

@Eric-Arellano Eric-Arellano moved this to In Progress in Docs Planning Dec 5, 2023
@Eric-Arellano Eric-Arellano self-assigned this Dec 5, 2023
@Eric-Arellano Eric-Arellano changed the title Tweak Qiskit release notes structure for future release notes Handle Qiskit release notes structure correctly to split out the notes by version Dec 11, 2023
@Eric-Arellano
Copy link
Collaborator Author

We decided in the Qiskit dev meeting after talking this over with @ElePT, @jakelishman, and @mtreinish that the changes should happen in this repo, not in Qiskit/qiskit. They value building the historical release notes in their local builds more than I realized.

They also do sometimes change prior release notes, such as fixing typos. It's important that Qiskit/documentation pulls in those changes, even if the release notes changed don't correspond to the current version of the docs we're building. For example, if we're building 1.1 docs, we should still see if there were any updates to 1.0 release notes.

So, this issue now tracks us improving updateApiDocs.ts to properly handle release notes for Qiskit. It will still only look for the file release_notes.html, but it needs to properly split out the file into its distinct minor releases, such as by using the logic from the PR description in #346.

@Eric-Arellano Eric-Arellano moved this from In Progress to In Review in Docs Planning Dec 29, 2023
github-merge-queue bot pushed a commit that referenced this issue Dec 29, 2023
This PR changes how we write the Qiskit `release-notes.html` to
correctly split the notes by version, updating the previous files if we
find any change. If we already have a file for the version we updated,
the script adds the new entries without overwriting the file and sorts
the entries by patch. If the patch we modified was already in the
version file, it substitutes its section for the new one.

Qiskit v0.45 has been regenerated using the new script to split
correctly versions 0.45 and 0.25 to remove the last one from the file.
Historical release notes files (< 0.45) will no longer be updated in the
regeneration. For more information see:
Qiskit/qiskit#11436

Command used:
`npm run gen-api -- -p qiskit -v 0.45.0 -a
https://github.com/Qiskit/qiskit/suites/17881600359/artifacts/1026798160`

Closes #359

---------

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
@github-project-automation github-project-automation bot moved this from In Review to Done in Docs Planning Dec 29, 2023
frankharkins pushed a commit to frankharkins/documentation that referenced this issue Jul 22, 2024
This PR changes how we write the Qiskit `release-notes.html` to
correctly split the notes by version, updating the previous files if we
find any change. If we already have a file for the version we updated,
the script adds the new entries without overwriting the file and sorts
the entries by patch. If the patch we modified was already in the
version file, it substitutes its section for the new one.

Qiskit v0.45 has been regenerated using the new script to split
correctly versions 0.45 and 0.25 to remove the last one from the file.
Historical release notes files (< 0.45) will no longer be updated in the
regeneration. For more information see:
Qiskit/qiskit#11436

Command used:
`npm run gen-api -- -p qiskit -v 0.45.0 -a
https://github.com/Qiskit/qiskit/suites/17881600359/artifacts/1026798160`

Closes Qiskit#359

---------

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Archived in project
Development

Successfully merging a pull request may close this issue.

2 participants