Convert deprecation policy and maintainer guide to markdown #11218

javabster · 2023-11-08T22:22:03Z

Summary

This PR creates markdown versions of the deprecation policy and maintainer guide, so we can safely remove https://qiskit.org/documentation/deprecation_policy.html and https://qiskit.org/documentation/maintainers_guide.html

Details and comments

qiskit-bot · 2023-11-08T22:22:07Z

One or more of the the following people are requested to review this:

@Qiskit/terra-core

coveralls · 2023-11-08T22:54:48Z

Pull Request Test Coverage Report for Build 6935485297

0 of 0 changed or added relevant lines in 0 files are covered.
10 unchanged lines in 2 files lost coverage.
Overall coverage increased (+0.01%) to 85.887%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	4	92.17%
crates/qasm2/src/parse.rs	6	97.13%

Totals
Change from base Build 6935431635:	0.01%
Covered Lines:	66359
Relevant Lines:	77263

💛 - Coveralls

Eric-Arellano

Thank you, Abby!

DEPRECATION.md

MAINTAINING.md

Co-authored-by: Eric Arellano <[email protected]>

jakelishman

This generally seems fine to me in principle, although I do think that it's a regression to move from hosting this in a properly rendered documentation build GitHub markdown views.

Should this PR also remove the old versions of these files?

There are other open PRs that are modifying the related files here, such as #11205, which have logical conflicts.

DEPRECATION.md

jakelishman · 2023-11-14T13:58:11Z

DEPRECATION.md

+- The alternative path must be in place for one minor version before any
+   warnings are issued.  For example, if we want to replace the function `foo()`


In all the bullets in this list, the continuation-line indentation looks like it's got an extra space in it. Not that it affects the display, it just makes it a bit harder to update.

DEPRECATION.md

jakelishman · 2023-11-14T14:00:59Z

DEPRECATION.md

+*migration guide* might be needed. Please write these guides in Qiskit's documentation at
+https://github.com/Qiskit/documentation/tree/main/docs/api/migration-guides. Once
+the migration guide is written and published, deprecation
+messages and documentation should link to it (use the `additional_msg: str` argument for


Minor style: I don't think we need to include the type hint for an argument when mentioning it in prose.

I added this a few months ago. I think it's useful for people to know what the argument is referring to. I agree it's not "necessary", but I think it's useful for only 5 extra characters.

I'd have thought the API documentation is a more appropriate place for this. To me it adds noise and makes it harder to scan (especially because this is the second time it happens).

jakelishman · 2023-11-14T14:01:37Z

MAINTAINING.md

+Refer to https://qiskit.github.io/qiskit_sphinx_theme/apidocs/index.html for how to create and
+write effective API documentation, such as setting up the RST files and docstrings.


Is this still going to be a relevant link after the full 1XP migration?

Yes. This site will still exist for the sake of the Qiskit Ecosystem. Its guidance on API docs should still be relevant for Qiskit itself.

Eric-Arellano · 2023-11-14T15:14:07Z

Should this PR also remove the old versions of these files?

Not yet. We're going to set up redirects from the qiskit.org pages to these markdown files as part of Qiskit/documentation#216 (still WIP!)

jakelishman · 2023-11-14T15:55:44Z

I think this PR should still remove the files from this repository; Qiskit/documentation should just not deploy the removal until its redirects are set up. Doing it split in this repo means there's more time for the files to get out of sync without detection (as it stands, the linked PR above won't detect a merge conflict because this PR doesn't remove the old files), and because this repo should have its docs in a consistent state.

Eric-Arellano · 2023-11-14T16:37:48Z

I think this PR should still remove the files from this repository;

I realize that will only impact qiskit.org/documentation/dev and not the current docs. So that works for me.

Co-authored-by: Jake Lishman <[email protected]>

javabster · 2023-11-17T19:00:29Z

The only reason I'd see for not removing the files yet in this PR is in case we need to do any emergency qiskit.org docs deployments between now and the redirects kicking in on 29th Nov. If we're fine risking that then I'll remove the files, I don't have a strong opinion either way.

At some point (out of scope for this PR) we should also remove the old tutorials and how-to guides etc as well, they've all been either migrated or superseded by 1docs content. We can check the commit history to see if anything was added since the migration or 0.45 release that isn't in 1docs

Co-authored-by: Jake Lishman <[email protected]>

Eric-Arellano · 2023-11-17T21:16:36Z

docs/index.rst

-
-   contributing_to_qiskit
-   deprecation_policy
-   maintainers_guide


Did you mean to delete this file and contributing_to_qiskit.rst too?

yeah jake asked me to remove it in the other contributing guide PR as well so just thought i'd do it in both to avoid merge conflicts whichever gets merged first

although i realise now that plan has backfired 🫠

Yeah, this PR will want to delete the maintainers guide and deprecation policy, but leave contributing guide. You'll get a merge conflict with your PR, but such it is 🤷

jakelishman

Thanks for the changes, Abby. Similar to #11217, if you're worried about not being ready for this change on the backend yet, shall we leave this approved but unmerged til you're ready?

Having the old files removed in the PR means we can't accidentally lose any changes from other PRs to the old file, because git will force us to resolve a merge conflict, so we fail safe in that case.

(btw, I know there's a docs-build failure just because of the contributing_to_qiskit.rst file being orphaned at the moment - it's just an approval in spirit, rather than knowing we're immediately going to merge, since I assume #11218 will go first.)

This PR replaces any qiskit.org links with 1XP or github equivalents. Need to wait to merge until I can update the deprecation policy and maintainer guide links after Qiskit/qiskit#11218 merges. This should partially resolve #297 , however for the api links we'll need to make updates for those directly in the repos where the API refs live (maybe this is beyond the scope of the original issue?) --------- Co-authored-by: Eric Arellano <[email protected]>

…1218) * Converted deprecation policy and maintainer guide to markdown * Apply suggestions from code review Co-authored-by: Eric Arellano <[email protected]> * Added more context around writing docs * Update DEPRECATION.md Co-authored-by: Jake Lishman <[email protected]> * fixed some formatting issues * Removed deprecation_policy.rst and maintainers_guide.rst * Apply suggestions from code review Co-authored-by: Jake Lishman <[email protected]> * update index.rst --------- Co-authored-by: Eric Arellano <[email protected]> Co-authored-by: Jake Lishman <[email protected]>

This PR replaces any qiskit.org links with 1XP or github equivalents. Need to wait to merge until I can update the deprecation policy and maintainer guide links after Qiskit/qiskit#11218 merges. This should partially resolve Qiskit#297 , however for the api links we'll need to make updates for those directly in the repos where the API refs live (maybe this is beyond the scope of the original issue?) --------- Co-authored-by: Eric Arellano <[email protected]>

Converted deprecation policy and maintainer guide to markdown

0b06ee1

javabster requested a review from a team as a code owner November 8, 2023 22:22

Eric-Arellano previously approved these changes Nov 9, 2023

View reviewed changes

Eric-Arellano mentioned this pull request Nov 9, 2023

Prepare Contributor guides to be readable directly in GitHub Qiskit/documentation#290

Closed

javabster dismissed Eric-Arellano’s stale review via 7df2ed8 November 13, 2023 19:28

Apply suggestions from code review

7df2ed8

Co-authored-by: Eric Arellano <[email protected]>

Eric-Arellano previously approved these changes Nov 13, 2023

View reviewed changes

Added more context around writing docs

14afc91

javabster dismissed Eric-Arellano’s stale review via 14afc91 November 13, 2023 20:59

jakelishman reviewed Nov 14, 2023

View reviewed changes

mtreinish mentioned this pull request Nov 16, 2023

Document versioning and deprecation policy for major versions #11205

Closed

Update DEPRECATION.md

ac0e0db

Co-authored-by: Jake Lishman <[email protected]>

javabster and others added 4 commits November 17, 2023 14:35

fixed some formatting issues

2575ed9

Removed deprecation_policy.rst and maintainers_guide.rst

ef7547a

Apply suggestions from code review

492cccc

Co-authored-by: Jake Lishman <[email protected]>

update index.rst

42968b3

Eric-Arellano reviewed Nov 17, 2023

View reviewed changes

jakelishman previously approved these changes Nov 17, 2023

View reviewed changes

Merge branch 'main' into maintainer-docs

9e91109

javabster dismissed jakelishman’s stale review via 9e91109 November 20, 2023 20:31

javabster mentioned this pull request Nov 20, 2023

Audited qiskit.org links Qiskit/documentation#381

Merged

jakelishman approved these changes Nov 20, 2023

View reviewed changes

jakelishman enabled auto-merge November 20, 2023 20:51

jakelishman added this pull request to the merge queue Nov 20, 2023

Merged via the queue into Qiskit:main with commit 45e4252 Nov 20, 2023
14 checks passed

jakelishman mentioned this pull request Jan 8, 2024

Deprecate qiskit.Aer and qiskit.providers.aer #11439

Merged

jakelishman mentioned this pull request Feb 12, 2024

Update deprecation policy document for Qiskit 1.0 #11775

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Convert deprecation policy and maintainer guide to markdown #11218

Convert deprecation policy and maintainer guide to markdown #11218

javabster commented Nov 8, 2023

qiskit-bot commented Nov 8, 2023

coveralls commented Nov 8, 2023 •

edited

Loading

Eric-Arellano left a comment

jakelishman left a comment

jakelishman Nov 14, 2023

jakelishman Nov 14, 2023

Eric-Arellano Nov 14, 2023

jakelishman Nov 14, 2023

jakelishman Nov 14, 2023

Eric-Arellano Nov 14, 2023

Eric-Arellano commented Nov 14, 2023

jakelishman commented Nov 14, 2023

Eric-Arellano commented Nov 14, 2023

javabster commented Nov 17, 2023

Eric-Arellano Nov 17, 2023

javabster Nov 17, 2023

javabster Nov 17, 2023

Eric-Arellano Nov 17, 2023

jakelishman left a comment •

edited

Loading

		- The alternative path must be in place for one minor version before any
		warnings are issued. For example, if we want to replace the function `foo()`

		Refer to https://qiskit.github.io/qiskit_sphinx_theme/apidocs/index.html for how to create and
		write effective API documentation, such as setting up the RST files and docstrings.

Convert deprecation policy and maintainer guide to markdown #11218

Convert deprecation policy and maintainer guide to markdown #11218

Conversation

javabster commented Nov 8, 2023

Summary

Details and comments

qiskit-bot commented Nov 8, 2023

coveralls commented Nov 8, 2023 • edited Loading

Pull Request Test Coverage Report for Build 6935485297

💛 - Coveralls

Eric-Arellano left a comment

Choose a reason for hiding this comment

jakelishman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Eric-Arellano commented Nov 14, 2023

jakelishman commented Nov 14, 2023

Eric-Arellano commented Nov 14, 2023

javabster commented Nov 17, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jakelishman left a comment • edited Loading

Choose a reason for hiding this comment

coveralls commented Nov 8, 2023 •

edited

Loading

jakelishman left a comment •

edited

Loading