From 28a1098ef66e8ce9f23cf4bd59e7091f9a273039 Mon Sep 17 00:00:00 2001
From: Frank Harkins <frankharkins@hotmail.co.uk>
Date: Thu, 25 Jul 2024 13:03:39 +0100
Subject: [PATCH 1/6] Add scaffolding

---
 docs/open-source/_toc.json          |  9 ++++
 docs/open-source/best-practices.mdx | 65 +++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 docs/open-source/best-practices.mdx

diff --git a/docs/open-source/_toc.json b/docs/open-source/_toc.json
index 946321b596..b5ee83a574 100644
--- a/docs/open-source/_toc.json
+++ b/docs/open-source/_toc.json
@@ -39,6 +39,15 @@
           "url": "https://github.com/Qiskit/qiskit/blob/main/MAINTAINING.md"
         }
       ]
+    },
+    {
+      "title": "Creating a Qiskit-based project",
+      "children": [
+        {
+          "title": "Best practices for your project",
+          "url": "/open-source/best-practices"
+        }
+      ]
     }
   ]
 }
diff --git a/docs/open-source/best-practices.mdx b/docs/open-source/best-practices.mdx
new file mode 100644
index 0000000000..55c5fc813f
--- /dev/null
+++ b/docs/open-source/best-practices.mdx
@@ -0,0 +1,65 @@
+---
+title: Best practices for your project
+description: Testing, packaging, and code quality best practices for your Python project.
+---
+
+# Best practices for your project
+
+* Why you should care
+  * Improves user experience
+    * Installation
+    * Testing for stability
+    * Documentation: See dedicated page
+  * Makes working with the repo easier
+    * Testing == less frustration
+    * Linters == neatness
+    * Both help others contribute to your project
+    * Contributors documentation: See dedicated page
+  * Security
+
+## Choose a license
+
+* No license ~= can't use
+* Choose from available licenses (link to OSC)
+* Explain GPL vs Apache etc.
+
+## Dependency management
+
+* Project will rely on other packages
+  * If you don't state this clearly, it's hard to get things working again
+
+* Simple requirements.txt file
+* Setting up poetry
+* Link: Security with dependabot
+
+## Test your project
+
+* Tests ensure your code does a certain thing and should make development easier
+  * If the tests pass, your code is good
+  * Makes it easy to refactor or add new features
+
+* unittest or pytest
+* Setting up pytest w/ simple example
+
+## Code quality tools
+
+* black
+* pylint
+* mypy
+
+## Package your project
+
+* Makes it easy for users to install
+  * Good for adoption and reproducability
+
+* Packaging for PyPI (`pip install ...`)
+* Make it easy to release with an action
+* Integrating with Qiskit
+  * Provider
+  * Transpiler plugin
+
+## Security
+
+* Set up 2FA on GitHub
+* Make sure your dependences are secure with dependabot
+* Set up branch protection

From cfbb9ab41bff2ba52a01dbd8e510723efdcb95d5 Mon Sep 17 00:00:00 2001
From: Frank Harkins <frankharkins@hotmail.co.uk>
Date: Thu, 25 Jul 2024 13:07:13 +0100
Subject: [PATCH 2/6] Flesh out intro, licensing, and dependencies

---
 docs/open-source/best-practices.mdx | 50 ++++++++++++++++++-----------
 1 file changed, 31 insertions(+), 19 deletions(-)

diff --git a/docs/open-source/best-practices.mdx b/docs/open-source/best-practices.mdx
index 55c5fc813f..7fd8805e1d 100644
--- a/docs/open-source/best-practices.mdx
+++ b/docs/open-source/best-practices.mdx
@@ -5,32 +5,44 @@ description: Testing, packaging, and code quality best practices for your Python
 
 # Best practices for your project
 
-* Why you should care
-  * Improves user experience
-    * Installation
-    * Testing for stability
-    * Documentation: See dedicated page
-  * Makes working with the repo easier
-    * Testing == less frustration
-    * Linters == neatness
-    * Both help others contribute to your project
-    * Contributors documentation: See dedicated page
-  * Security
+If you have an idea for a Qiskit-based project, you'll often want to share it
+with the community. Putting your code online is a good start, but if a user
+can't work out how to install or use your project, they'll give up and move on.
+This page covers licensing, packaging, testing, and documenting your project,
+all of which improve users' experience. If you're releasing research code,
+following best practices will also help others reproduce your results.
 
 ## Choose a license
 
-* No license ~= can't use
-* Choose from available licenses (link to OSC)
-* Explain GPL vs Apache etc.
+If you want others to use your project, you *must* choose an appropriate
+license. Otherwise, your grant no permission for others to use it. Most
+projects in the [Qiskit ecosystem](https://www.ibm.com/quantum/ecosystem) use
+the Apache 2.0 or MIT licenses. Visit GitHub's [choosealicense.com](https://choosealicense.com) to
+decide which license is best for you.
+
+Add your license to the top level of your repository in a text file named
+`LICENSE`. When you create a new repository, GitHub will give you the option to
+automatically add a standard license.
 
 ## Dependency management
 
-* Project will rely on other packages
-  * If you don't state this clearly, it's hard to get things working again
+If you don't clearly specify your project's dependencies, users (including your
+future self) will struggle to install and use it.
+
+The simplest way to list your requirements is to put the Python version you're
+using in your `README` and include a
+[`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/)
+file in your repository. However, this means you must manually identify your
+requirements and keep the file in sync.
+
+Tools such as [Poetry](https://python-poetry.org/) solve this problem by
+managing dependencies for you, which means they can keep track of everything
+you've installed. Installing a dependency through Poetry will add it to a
+"lock" file, which keeps track of the exact versions of each package you have
+installed. Users can use the lockfile to replicate your environment.
 
-* Simple requirements.txt file
-* Setting up poetry
-* Link: Security with dependabot
+See [Poetry: Basic usage](https://python-poetry.org/docs/basic-usage/) to set
+up your project with Poetry.
 
 ## Test your project
 

From f5485f859c89dcf0dbc615928c26fa5b66618428 Mon Sep 17 00:00:00 2001
From: Frank Harkins <frankharkins@hotmail.co.uk>
Date: Thu, 25 Jul 2024 15:29:01 +0100
Subject: [PATCH 3/6] Edit scaffolding

---
 docs/open-source/best-practices.mdx | 40 ++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 9 deletions(-)

diff --git a/docs/open-source/best-practices.mdx b/docs/open-source/best-practices.mdx
index 7fd8805e1d..5c61d715c5 100644
--- a/docs/open-source/best-practices.mdx
+++ b/docs/open-source/best-practices.mdx
@@ -1,5 +1,5 @@
 ---
-title: Best practices for your project
+title: Project setup and best practices
 description: Testing, packaging, and code quality best practices for your Python project.
 ---
 
@@ -12,6 +12,23 @@ This page covers licensing, packaging, testing, and documenting your project,
 all of which improve users' experience. If you're releasing research code,
 following best practices will also help others reproduce your results.
 
+Once you've .... add your project to the ecosystem.
+
+## GitHub
+
+* GitHub actions
+* CI
+* Contributing guide
+* Code of conduct
+* Branch protection
+* Squash and merge
+
+### Security
+
+* Dependabot
+* 2FA
+* Branch protection
+
 ## Choose a license
 
 If you want others to use your project, you *must* choose an appropriate
@@ -46,6 +63,9 @@ up your project with Poetry.
 
 ## Test your project
 
+Tests are small functions you'll write to make sure your code is working correctly.
+A test 
+
 * Tests ensure your code does a certain thing and should make development easier
   * If the tests pass, your code is good
   * Makes it easy to refactor or add new features
@@ -53,11 +73,16 @@ up your project with Poetry.
 * unittest or pytest
 * Setting up pytest w/ simple example
 
+* Mention tox in admonition for multiple python versions (not dep management)
+
 ## Code quality tools
 
-* black
-* pylint
+* ruff
 * mypy
+* bandit (Security linter)
+* others such as isort, pyupgrade
+
+* Link to CI section
 
 ## Package your project
 
@@ -65,13 +90,10 @@ up your project with Poetry.
   * Good for adoption and reproducability
 
 * Packaging for PyPI (`pip install ...`)
+  * pyproject.toml (not setup.py)
+  * setuptools
 * Make it easy to release with an action
+  * check sphinx-theme (release guide) / rustworkx
 * Integrating with Qiskit
   * Provider
   * Transpiler plugin
-
-## Security
-
-* Set up 2FA on GitHub
-* Make sure your dependences are secure with dependabot
-* Set up branch protection

From 322d8ec396a5a51311825cc40546126368b5f8c5 Mon Sep 17 00:00:00 2001
From: Frank Harkins <frankharkins@hotmail.co.uk>
Date: Thu, 29 Aug 2024 14:19:41 +0100
Subject: [PATCH 4/6] Flesh out bullet points

---
 docs/open-source/best-practices.mdx | 107 +++++++++++++++++-----------
 1 file changed, 66 insertions(+), 41 deletions(-)

diff --git a/docs/open-source/best-practices.mdx b/docs/open-source/best-practices.mdx
index 5c61d715c5..a3fa70d696 100644
--- a/docs/open-source/best-practices.mdx
+++ b/docs/open-source/best-practices.mdx
@@ -9,33 +9,56 @@ If you have an idea for a Qiskit-based project, you'll often want to share it
 with the community. Putting your code online is a good start, but if a user
 can't work out how to install or use your project, they'll give up and move on.
 This page covers licensing, packaging, testing, and documenting your project,
-all of which improve users' experience. If you're releasing research code,
+all of which improve your users' experience. If you're releasing research code,
 following best practices will also help others reproduce your results.
 
-Once you've .... add your project to the ecosystem.
+Once you've polished it up, consider adding your project to the [Qiskit
+ecosystem](https://www.ibm.com/quantum/ecosystem).
 
 ## GitHub
 
-* GitHub actions
-* CI
-* Contributing guide
-* Code of conduct
-* Branch protection
-* Squash and merge
-
-### Security
-
-* Dependabot
-* 2FA
-* Branch protection
+Most Qiskit projects are hosted on [GitHub](https://github.com/), a source-code
+hosting platform. GitHub is based on [Git](https://git-scm.com/) (a version
+control system) and provides a large set of tools to help collaborate on your
+project and keep it to a high quality. See [Github
+skills](https://skills.github.com/) to get up to speed on GitHub quickly. The
+rest of this page will assume you have your project hosted on GitHub.
+
+Some key features are:
+
+* **Issues and Pull requests:** Users can use issues to report bugs in your
+  project or request changes to it. Your team and external contributors can use
+  pull requests to propose and review changes to your project.
+
+  If you want to accept contributions from others, make sure to add a
+  [contributing
+  guide](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
+  and a [code of
+  conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project).
+
+* **GitHub actions:** This feature runs scripts when certain events happen in
+  your GitHub repo. For example, you can run your [test
+  suite](#test-your-project) when you push new code or automatically
+  [publishing your package](#publish-to-pypi) when you tag a commit.
+
+* **Security features:** These include
+  * [Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates)
+    – a tool to automatically update your dependencies.
+  * [Trusted publishing to PyPI](https://docs.pypi.org/trusted-publishers/) –
+    to reduce the risk of a malicious actor gaining control of your package.
+  * [Branch
+    protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)
+    – to make sure code meets some criteria before being pushed to certain
+    branches.
 
 ## Choose a license
 
 If you want others to use your project, you *must* choose an appropriate
 license. Otherwise, your grant no permission for others to use it. Most
 projects in the [Qiskit ecosystem](https://www.ibm.com/quantum/ecosystem) use
-the Apache 2.0 or MIT licenses. Visit GitHub's [choosealicense.com](https://choosealicense.com) to
-decide which license is best for you.
+the Apache 2.0 or MIT licenses. Visit GitHub's
+[choosealicense.com](https://choosealicense.com) to decide which license is
+best for you.
 
 Add your license to the top level of your repository in a text file named
 `LICENSE`. When you create a new repository, GitHub will give you the option to
@@ -63,37 +86,39 @@ up your project with Poetry.
 
 ## Test your project
 
-Tests are small functions you'll write to make sure your code is working correctly.
-A test 
+Tests are small functions you'll write to make sure your code is working
+correctly. A good test suite makes working on your code easier; if the tests
+pass, your code is good. This means you can be confident you haven't broken
+anything when refactoring or adding new features. Seeing tests in a project's
+repository gives users more confidence in the stability of the project.
 
-* Tests ensure your code does a certain thing and should make development easier
-  * If the tests pass, your code is good
-  * Makes it easy to refactor or add new features
+The two most popular testing frameworks in Python are:
+* Python's built-in [`unittest`](https://docs.python.org/3/library/unittest.html)
+* [`pytest`](https://docs.pytest.org/en/stable/)
 
-* unittest or pytest
-* Setting up pytest w/ simple example
-
-* Mention tox in admonition for multiple python versions (not dep management)
+You can also consider using [`tox`](https://tox.wiki/en/4.18.0/) to test your
+project against different versions of Python.
 
 ## Code quality tools
 
-* ruff
-* mypy
-* bandit (Security linter)
-* others such as isort, pyupgrade
+A linter is a tool that detects (and sometimes corrects) common problems in
+your code. A popular linter for Python is
+[`ruff`](https://docs.astral.sh/ruff/). Other popular tools include
+[`mypy`](https://www.mypy-lang.org/) for type-checking, and
+[`bandit`](https://bandit.readthedocs.io/en/latest/) for security scanning.
 
-* Link to CI section
+Once you've set your tools up, you can use a [GitHub action](#github) to make
+sure all code pushed to your repository has been linted.
 
 ## Package your project
 
-* Makes it easy for users to install
-  * Good for adoption and reproducability
-
-* Packaging for PyPI (`pip install ...`)
-  * pyproject.toml (not setup.py)
-  * setuptools
-* Make it easy to release with an action
-  * check sphinx-theme (release guide) / rustworkx
-* Integrating with Qiskit
-  * Provider
-  * Transpiler plugin
+Consider [packaging your Python
+project](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+to make it easy for others to install and use. You should also consider
+uploading your package to [PyPI](https://pypi.org/) so it can be installed
+through `pip`.
+
+If your project is a transpiler plugin, see [Create a transpiler
+plugin](/guides/create-transpiler-plugin) to integrate correctly with Qiskit's
+transpiler. This makes it easy for users to incorporate your plugin into their
+Qiskit code.

From 480cb1c382670ba456ffc3eb625eda6213046845 Mon Sep 17 00:00:00 2001
From: Frank Harkins <frankharkins@hotmail.co.uk>
Date: Thu, 29 Aug 2024 14:19:50 +0100
Subject: [PATCH 5/6] Rearrange

---
 docs/open-source/best-practices.mdx | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/open-source/best-practices.mdx b/docs/open-source/best-practices.mdx
index a3fa70d696..d93043d20e 100644
--- a/docs/open-source/best-practices.mdx
+++ b/docs/open-source/best-practices.mdx
@@ -84,6 +84,19 @@ installed. Users can use the lockfile to replicate your environment.
 See [Poetry: Basic usage](https://python-poetry.org/docs/basic-usage/) to set
 up your project with Poetry.
 
+## Package your project
+
+Consider [packaging your Python
+project](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+to make it easy for others to install and use. You should also consider
+uploading your package to [PyPI](https://pypi.org/) so it can be installed
+through `pip`.
+
+If your project is a transpiler plugin, see [Create a transpiler
+plugin](/guides/create-transpiler-plugin) to integrate correctly with Qiskit's
+transpiler. This makes it easy for users to incorporate your plugin into their
+Qiskit code.
+
 ## Test your project
 
 Tests are small functions you'll write to make sure your code is working
@@ -109,16 +122,3 @@ your code. A popular linter for Python is
 
 Once you've set your tools up, you can use a [GitHub action](#github) to make
 sure all code pushed to your repository has been linted.
-
-## Package your project
-
-Consider [packaging your Python
-project](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
-to make it easy for others to install and use. You should also consider
-uploading your package to [PyPI](https://pypi.org/) so it can be installed
-through `pip`.
-
-If your project is a transpiler plugin, see [Create a transpiler
-plugin](/guides/create-transpiler-plugin) to integrate correctly with Qiskit's
-transpiler. This makes it easy for users to incorporate your plugin into their
-Qiskit code.

From cfddf166725d2867fcdc44e06523443c618e7c51 Mon Sep 17 00:00:00 2001
From: Frank Harkins <frankharkins@hotmail.co.uk>
Date: Thu, 29 Aug 2024 16:29:46 +0100
Subject: [PATCH 6/6] tweaks

---
 docs/open-source/best-practices.mdx | 32 ++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 12 deletions(-)

diff --git a/docs/open-source/best-practices.mdx b/docs/open-source/best-practices.mdx
index d93043d20e..6821971840 100644
--- a/docs/open-source/best-practices.mdx
+++ b/docs/open-source/best-practices.mdx
@@ -21,14 +21,15 @@ Most Qiskit projects are hosted on [GitHub](https://github.com/), a source-code
 hosting platform. GitHub is based on [Git](https://git-scm.com/) (a version
 control system) and provides a large set of tools to help collaborate on your
 project and keep it to a high quality. See [Github
-skills](https://skills.github.com/) to get up to speed on GitHub quickly. The
-rest of this page will assume you have your project hosted on GitHub.
+skills](https://skills.github.com/) to get up to speed on GitHub quickly.
 
 Some key features are:
 
-* **Issues and Pull requests:** Users can use issues to report bugs in your
-  project or request changes to it. Your team and external contributors can use
-  pull requests to propose and review changes to your project.
+* **Issues and Pull requests**
+
+  Users can use GitHub to report bugs in your project or request changes to it.
+  Your team and external contributors can use pull requests to propose and
+  review changes to your project's code.
 
   If you want to accept contributions from others, make sure to add a
   [contributing
@@ -36,12 +37,17 @@ Some key features are:
   and a [code of
   conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project).
 
-* **GitHub actions:** This feature runs scripts when certain events happen in
-  your GitHub repo. For example, you can run your [test
-  suite](#test-your-project) when you push new code or automatically
-  [publishing your package](#publish-to-pypi) when you tag a commit.
+* **GitHub actions**
+
+  This feature runs scripts when certain events happen in your GitHub repo. For
+  example, you can run your [test suite](#test-your-project) when you push new
+  code or automatically [publishing your package](#package-your-project) when
+  you tag a commit.
+
+* **Security features**
+
+  GitHub supports features to keep your projects secure. These include:
 
-* **Security features:** These include
   * [Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates)
     – a tool to automatically update your dependencies.
   * [Trusted publishing to PyPI](https://docs.pypi.org/trusted-publishers/) –
@@ -51,6 +57,8 @@ Some key features are:
     – to make sure code meets some criteria before being pushed to certain
     branches.
 
+The rest of this page will assume you have your project hosted on GitHub.
+
 ## Choose a license
 
 If you want others to use your project, you *must* choose an appropriate
@@ -101,13 +109,13 @@ Qiskit code.
 
 Tests are small functions you'll write to make sure your code is working
 correctly. A good test suite makes working on your code easier; if the tests
-pass, your code is good. This means you can be confident you haven't broken
+pass, your code works. This means you can be confident you haven't broken
 anything when refactoring or adding new features. Seeing tests in a project's
 repository gives users more confidence in the stability of the project.
 
 The two most popular testing frameworks in Python are:
-* Python's built-in [`unittest`](https://docs.python.org/3/library/unittest.html)
 * [`pytest`](https://docs.pytest.org/en/stable/)
+* Python's built-in [`unittest`](https://docs.python.org/3/library/unittest.html)
 
 You can also consider using [`tox`](https://tox.wiki/en/4.18.0/) to test your
 project against different versions of Python.