Add community tutorial contribution guidelines

.github/ISSUE_TEMPLATE/tutorial-proposal.yaml

@@ -0,0 +1,130 @@
+name: (Tutorials 📓) Propose a community tutorial
+description: Propose a new Foundational or Applied tutorial to contribute to the Qiskit tutorials
+title: "[Tutorial proposal] "
+labels: ["content 📄", "tutorial 📒", "needs triage 🤔"]
+assignees:
+  - henryzou50
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for proposing a tutorial! Before you start, read [Contribute a tutorial](https://quantum.cloud.ibm.com/docs/tutorials/contribute) for what can be contributed and the requirements for each kind of tutorial.
+
+        Search existing [tutorials](https://quantum.cloud.ibm.com/docs/tutorials) and [open proposals](https://github.com/Qiskit/documentation/issues?q=is%3Aissue+is%3Aopen+%22Tutorial+proposal%22) to avoid duplicates. The IBM Quantum tutorials team reviews each proposal, and a working-group member reviews the technical content. Wait for approval before you open a pull request.
+
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Tutorial type
+      options:
+        - Foundational
+        - Applied
+    validations:
+      required: true
+
+  - type: dropdown
+    id: domain
+    attributes:
+      label: Domain
+      description: Foundational optimization and Hamiltonian simulation tutorials, and Applied quantum information science tutorials, are written by the IBM Quantum team and are not open to contributions.
+      options:
+        - Optimization (Applied only)
+        - Hamiltonian simulation (Applied only)
+        - Quantum machine learning
+        - Quantum information science (Foundational only)
+    validations:
+      required: true
+
+  - type: input
+    id: target
+    attributes:
+      label: Open topic or problem class
+      description: For a Foundational tutorial, name the open topic. For an Applied tutorial, name the problem class. To propose a topic or problem class that is not listed, describe the gap it fills.
+    validations:
+      required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What does the tutorial show, and what do readers learn?
+    validations:
+      required: true
+
+  - type: input
+    id: paper
+    attributes:
+      label: Source paper
+      description: Link to the paper the tutorial is based on, if any.
+    validations:
+      required: false
+
+  - type: textarea
+    id: bar
+    attributes:
+      label: How it meets the requirements
+      description: |
+        Foundational: which step of the Applied tutorial or problem class listed for the topic it prepares readers for, and what it shows on hardware that a course does not.
+        Applied: which state-of-the-art criteria it meets, and, if the class already has a tutorial that uses your method, how your proposal improves that tutorial.
+    validations:
+      required: true
+
+  - type: textarea
+    id: circuits
+    attributes:
+      label: Circuit and hardware details
+      description: Number of qubits, two-qubit depth, two-qubit gate count, estimated QPU time, and how you plan to get access to IBM Quantum hardware.
+    validations:
+      required: true
+
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification plan
+      description: The small instance you plan to run, the known answer you compare against, and the tolerance.
+    validations:
+      required: true
+
+  - type: textarea
+    id: baseline
+    attributes:
+      label: Classical baseline
+      description: The classical method you compare against on the same instance. Required for Applied tutorials.
+    validations:
+      required: false
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies
+      description: Packages beyond Qiskit, with pinned versions. Quantum packages must be on the approved list on the Contribute a tutorial page, and classical packages must be published on PyPI. To request a package that is not on the list, name it here and explain why you need it.
+    validations:
+      required: false
+
+  - type: textarea
+    id: authors
+    attributes:
+      label: Authors and affiliations
+    validations:
+      required: true
+
+  - type: input
+    id: timeline
+    attributes:
+      label: Expected timeline
+      description: When you expect to open the pull request.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: confirm
+    attributes:
+      label: Confirm
+      options:
+        - label: I read the contribution requirements.
+          required: true
+        - label: I searched existing tutorials and proposals for duplicates.
+          required: true
+        - label: I agree to respond within 30 days if a change breaks the tutorial after it is published.
+          required: true

docs/tutorials/_toc.json

@@ -329,6 +329,10 @@
           ]
         }
       ]
+    },
+    {
+      "title": "Contribute a tutorial",
+      "url": "/docs/tutorials/contribute"
     }
   ]
 }

docs/tutorials/contribute.mdx

@@ -0,0 +1,143 @@
+---
+title: Contribute a tutorial
+description: Learn which tutorials the community can contribute, the requirements for Foundational and Applied tutorials, and how to propose one
+---
+
+{/* cspell:ignore Birkhoff Floquet Polaron QOBLIB Steane VLSI */}
+
+# Contribute a tutorial
+
+Qiskit tutorials on IBM Quantum® Platform are open to community contributions. This page explains which tutorials you can contribute, what each kind of tutorial must show, and how to propose one.
+
+Every tutorial belongs to a domain (optimization, Hamiltonian simulation, quantum machine learning, or quantum information science) and is either Foundational or Applied:
+
+- **Foundational tutorials** teach the core ideas and canonical methods of a domain. They use well-known teaching problems, so that the method is the focus rather than the problem.
+- **Applied tutorials** are built around a specific goal: solving a particular problem from the problem classes on this page, or applying a specialized technique or tool in the setting where it can be used successfully. They assume strong familiarity with the fundamentals.
+
+In short, Foundational tutorials show how to use a method or tool, and Applied tutorials show the best current results on a specific problem.
+
+## What you can contribute
+
+| Domain | Foundational tutorials | Applied tutorials |
+| --- | --- | --- |
+| [Optimization](#optimization) | Written by the IBM Quantum team | 10 problem classes |
+| [Hamiltonian simulation](#hamiltonian-simulation) | Written by the IBM Quantum team | 10 problem classes |
+| [Quantum machine learning](#quantum-machine-learning) | 1 open topic | 7 problem classes |
+| [Quantum information science](#quantum-information-science) | 4 open topics | Written by the IBM Quantum team |
+
+## Requirements
+
+Every tutorial must:
+
+- Follow the tutorial template, use current Qiskit with no deprecated interfaces, and cover something that [IBM Quantum Learning](/learning) courses and existing tutorials do not.
+- Use only the [approved quantum packages](#approved-quantum-packages), including Qiskit Functions, pin every package version, and keep custom code in the notebook.
+- Verify a small instance against a known answer (exact, analytic, or published) within a stated tolerance before scaling up.
+- Run on IBM Quantum hardware at about 50 qubits or more, and report the error mitigation settings and QPU time.
+
+Beyond these, Foundational and Applied tutorials differ in what they cover and the bar they meet:
+
+- **Foundational tutorials** teach how to use a method or tool on the teaching problem for an [open topic](#open-topics-and-problem-classes). They compare the method against a default approach as the problem grows, and end with a "Next steps" section that links to the Applied tutorial or problem class that the method leads to.
+- **Applied tutorials** solve a real instance from a [problem class](#open-topics-and-problem-classes), report its target quantity, and compare against a classical method on the same instance. They meet at least two of these state-of-the-art criteria: a peer-reviewed paper from the past three years, the largest hardware demonstration of the problem, or advanced features such as dynamic circuits. The hardware run uses a two-qubit depth of at least 50 unless the tutorial clearly meets the state-of-the-art bar, and anyone can reproduce it within its error bars on a current-generation backend. A tutorial built around a vendor's Qiskit Function is always Applied.
+
+If a problem class already has a tutorial that uses your method, propose an improvement to that tutorial instead of a new one. Reviewers weigh the trade-offs, such as better scale at a higher QPU cost, and an accepted improvement updates the existing tutorial.
+
+### Approved quantum packages
+
+The IBM Quantum team maintains this list. Install approved packages from PyPI, or from GitHub pinned to a release tag where the list says so. Classical packages, such as NumPy and SciPy, must be published on PyPI. To request a package that is not on the list, name it in your proposal and explain why you need it.
+
+| Area | Packages |
+| --- | --- |
+| Qiskit and IBM Quantum services | `qiskit`, `qiskit-ibm-runtime`, `qiskit-aer`, `qiskit-serverless`, `qrmi` |
+| Compilation | `qiskit-ibm-transpiler`, `qiskit-basis-constructor` |
+| Noise management | `samplomatic`, `qiskit-mitigation`, `qiskit-noise-learning`, `qiskit-paulice`, `mthree`, `qiskit-addon-cutting`, `qiskit-addon-obp`, `qiskit-addon-pna`, `qiskit-addon-slc` |
+| Simulation, chemistry, and optimization | `ffsim`, `qiskit-fermions`, `qiskit-addon-aqc-tensor`, `qiskit-addon-mpf`, `qiskit-addon-opt-mapper`, `qiskit-addon-sqd`, `qaoa_training_pipeline` (from GitHub) |
+| Benchmarking and characterization | `qiskit-experiments`, `gem-suite`, `qiskit-device-benchmarking` (from GitHub) |
+| Supporting tools | `qiskit-addon-utils`, `pauli-prop` |
+| Qiskit Functions | `qiskit-ibm-catalog`, plus any client package that a Function's provider requires, such as `qctrl-visualizer` or `luna-model` |
+
+## Open topics and problem classes
+
+For each domain, this section lists the teaching problem and open topics for Foundational tutorials, and the problem classes for Applied tutorials. To propose a problem class, or a quantum machine learning or quantum information science topic that is not listed, open a [proposal](#how-to-propose-a-tutorial) and explain the gap it fills.
+
+### Optimization
+
+Foundational tutorials use max-cut as the teaching problem. They are written by the IBM Quantum team, so community contributions target the problem classes below.
+
+Applied tutorials target one of the ten problem classes in the [Quantum Optimization Benchmarking Library (QOBLIB)](https://arxiv.org/abs/2504.03832):
+
+| Problem class | Description | Existing tutorials |
+| --- | --- | --- |
+| Market split | Multi-dimensional subset sum | [Solve the Market Split problem with Kipu Quantum's Iskay Quantum Optimizer](/docs/tutorials/solve-market-split-problem-with-iskay-quantum-optimizer)<br/>[Solve the market split problem with the ParityQC Parity Twine Optimizer](/docs/tutorials/parity-twine-optimizer-ms) |
+| Low autocorrelation binary sequences | Radar and communications sequence design | None yet |
+| Minimum Birkhoff decomposition | Doubly stochastic matrix decomposition | None yet |
+| Steiner tree packing | VLSI design and wire routing | None yet |
+| Sports tournament scheduling | Constraint satisfaction | None yet |
+| Portfolio optimization | Multi-period portfolios with transaction costs and short selling | [Dynamic portfolio optimization with Global Data Quantum's Portfolio Optimizer](/docs/tutorials/global-data-quantum-optimizer) |
+| Maximum independent set | Unweighted maximum independent set on graphs | [Find the maximum independent set with Aqarios Constrained Quantum Optimizer](/docs/tutorials/find-the-maximum-independent-set-with-aqarios-constrained-quantum-optimizer) |
+| Network design | Telecommunications network planning | None yet |
+| Vehicle routing | Vehicle routing with time windows and knapsack constraints | None yet |
+| Topology design | Graph golf (the degree-diameter problem) | None yet |
+
+### Hamiltonian simulation
+
+Foundational tutorials use one of two teaching problems: the N<sub>2</sub> molecule in a minimal basis for chemistry, or the one-dimensional Heisenberg or Ising chain for spin and lattice models. They are written by the IBM Quantum team, so community contributions target the problem classes below.
+
+Applied tutorials target one of the following problem classes:
+
+| Problem class | Target quantity | Existing tutorials |
+| --- | --- | --- |
+| Strongly correlated molecular ground states | Ground-state energy across geometries | [Sample-based quantum diagonalization of a chemistry Hamiltonian](/docs/tutorials/sample-based-quantum-diagonalization) (one geometry)<br/>[Dissociation PES curves with Qunova HiVQE](/docs/tutorials/qunova-hivqe) |
+| Nuclear shell-model ground states | Ground-state energy | [Pooled sample-based quantum diagonalization of a nuclear Hamiltonian](/docs/tutorials/nuclear-sqd-pooled) |
+| Electron-phonon dynamics | Polaron quench dynamics | None yet |
+| Lattice gauge real-time dynamics | String-breaking and hadron dynamics | [Observation of robust and coherent non-Abelian hadron dynamics on noisy quantum processors](/docs/tutorials/loop-string-hadron-dynamics) |
+| SYK scrambling (long-term target) | Out-of-time-order correlators and spectral form factor | None yet |
+| Frustrated magnets | Ground-state and finite-temperature observables | None yet |
+| Kicked and Floquet spin dynamics | Quench observables | [Simulation of kicked Ising Hamiltonian with dynamic circuits](/docs/tutorials/dc-hex-ising)<br/>[Transverse-Field Ising Model with Q-CTRL's Performance Management](/docs/tutorials/transverse-field-ising-model)<br/>[Simulate 2D tilted-field Ising with the QESEM function](/docs/tutorials/qedma-2d-ising-with-qesem)<br/>[Simulate a kicked Ising model with the TEM function](/docs/tutorials/simulate-kicked-ising-tem) |
+| Symmetric spin dynamics | Dynamical structure factor | [Simulate neutron scattering in quantum materials with quantum circuits](/docs/tutorials/simulate-neutron-scattering)<br/>[Simulate neutron scattering with an AQC + Trotter dynamics Serverless workflow](/docs/tutorials/simulate-neutron-scattering-with-a-serverless-workflow) |
+| Doped 2D Fermi-Hubbard dynamics | Charge and spin quench dynamics | None yet |
+| Quantum impurity models | Impurity Green's function | [Sample-based Krylov quantum diagonalization of a fermionic lattice model](/docs/tutorials/sample-based-krylov-quantum-diagonalization) (ground state only) |
+
+### Quantum machine learning
+
+Foundational tutorials use a small classification dataset with a classical baseline as the teaching problem. One Foundational topic is open:
+
+| Open topic | Leads to |
+| --- | --- |
+| Training and evaluating a quantum kernel classifier on a small dataset, with a classical baseline | Classification problem classes |
+
+Applied tutorials target one of the following problem classes:
+
+| Problem class | Target quantity | Existing tutorials |
+| --- | --- | --- |
+| Quantum phase classification | Test accuracy versus sample count | None yet |
+| Quantum property prediction | Samples needed to reach a target error | None yet |
+| Hamiltonian learning | Parameter error versus samples | None yet |
+| Generative learning of hard distributions | Sampling fidelity or cross-entropy | None yet |
+| Group-structured classification | Test accuracy | None yet |
+| Quantum reservoir and extreme learning | Prediction error or test accuracy | None yet |
+| Real-world tabular classification | Accuracy versus a matched classical model | [Enhance feature classification using projected quantum kernels](/docs/tutorials/projected-quantum-kernels)<br/>[Hybrid quantum-enhanced ensemble classification (grid stability workflow)](/docs/tutorials/sml-classification) |
+
+### Quantum information science
+
+Quantum information science has no problem classes, and its Applied tutorials are written by the IBM Quantum team. Foundational tutorials are open for the following topics only, and each topic names its own teaching problem.
+
+| Open topic | Teaching problem | Leads to |
+| --- | --- | --- |
+| Phase estimation at scale without vendor tools, for example iterative phase estimation with dynamic circuits | The one-dimensional transverse-field Ising chain, whose energies are known exactly | Energy estimation in Hamiltonian simulation |
+| Device benchmarking with cross-entropy benchmarking and random circuit sampling | Random circuits, simulated exactly at small sizes | Quantum advantage experiments |
+| Error correction beyond the repetition code, such as syndrome extraction with dynamic circuits | A small stabilizer code, such as the Steane code or the distance-3 surface code | [Low-overhead error detection with spacetime codes](/docs/tutorials/spacetime-codes) |
+| Fidelity estimation and certification of large entangled states | GHZ and graph states | Learning and certifying quantum states |
+
+## How to propose a tutorial
+
+Contributions go through two stages, so that you get feedback before you write the full tutorial.
+
+1. **Propose.** Open a [tutorial proposal issue](https://github.com/Qiskit/documentation/issues/new?template=tutorial-proposal.yaml) in the Qiskit documentation repository. Proposals are public, so you can check what others are already working on. The IBM Quantum tutorials team reviews each proposal against these requirements, and a member of the relevant working group reviews the technical content.
+2. **Submit.** After your proposal is approved, open a pull request from your fork that adds the notebook. Follow the [contributing guide](https://github.com/Qiskit/documentation/blob/main/CONTRIBUTING.md), including signing the [Contributor License Agreement](https://qisk.it/cla).
+
+## Authorship and maintenance
+
+- **Credit.** Contributed tutorials show a byline at the top with the authors' names and affiliations and a link to the source paper. Tutorial cards show a community tag.
+- **Maintainer of record.** Each contributed tutorial also has a maintainer of record from the IBM Quantum team, who keeps it running as Qiskit changes.
+- **Breaking changes.** If a change breaks the tutorial, the authors have 30 days to respond to the issue. If it is still unresolved after the next major Qiskit release, the tutorial is archived.
+- **Existing community tutorials.** These requirements apply to new contributions. Community tutorials that are already published get the community tag, and are held to these requirements when they are next updated.

docs/tutorials/index.mdx

@@ -10,6 +10,7 @@ Use these tutorials to learn how to apply Qiskit to common quantum computing use
 - Start with the set of tutorials in the [Get started](#get-started) section if it is your first time running code on a quantum computer.
 - The section on [workflows toward advantage](#explore-workflows-toward-advantage) contains end-to-end examples of using a quantum computer to solve real-world problems. These tutorials focus on algorithms that are promising candidates for achieving computational advantage by a quantum computer over a classical computer.
 - The section on [Qiskit capabilities](#leverage-qiskit-capabilities) contains examples that use the latest and most advanced techniques in the Qiskit ecosystem to improve part or the whole of a particular workflow.
+- To contribute a tutorial of your own, see [Contribute a tutorial](/docs/tutorials/contribute).
 
 ## Get started
 

qiskit_bot.yaml

@@ -739,6 +739,9 @@ notifications:
     - "@kaelynj"
   "docs/tutorials/index":
     - "`@nathanearnestnoble`"
+  "docs/tutorials/contribute":
+    - "`@nathanearnestnoble`"
+    - "`@henryzou50`"
   "docs/tutorials/time-evolution":
     - "`@nathanearnestnoble`"
     - "`@haimeng-zhang`"