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/9] 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 946321b596f..b5ee83a5741 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 00000000000..55c5fc813ff
--- /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/9] 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 55c5fc813ff..7fd8805e1dc 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/9] 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 7fd8805e1dc..5c61d715c5f 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/9] 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 5c61d715c5f..a3fa70d6965 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/9] 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 a3fa70d6965..d93043d20e2 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/9] 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 d93043d20e2..6821971840b 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.

From 492069768cf3d8d640d2e528af32f41abfc2e8d3 Mon Sep 17 00:00:00 2001
From: Frank Harkins <frankharkins@hotmail.co.uk>
Date: Thu, 10 Oct 2024 10:55:32 +0100
Subject: [PATCH 7/9] Apply suggestions from code review

Co-authored-by: abbycross <across@us.ibm.com>
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
---
 docs/open-source/_toc.json          |  2 +-
 docs/open-source/best-practices.mdx | 34 ++++++++++++++++++-----------
 2 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/docs/open-source/_toc.json b/docs/open-source/_toc.json
index 5d3ad2b0787..0e38acef69a 100644
--- a/docs/open-source/_toc.json
+++ b/docs/open-source/_toc.json
@@ -41,7 +41,7 @@
       ]
     },
     {
-      "title": "Creating a Qiskit-based project",
+      "title": "Create a Qiskit-based project",
       "children": [
         {
           "title": "Best practices for your project",
diff --git a/docs/open-source/best-practices.mdx b/docs/open-source/best-practices.mdx
index 6821971840b..71fea8b69c6 100644
--- a/docs/open-source/best-practices.mdx
+++ b/docs/open-source/best-practices.mdx
@@ -1,6 +1,6 @@
 ---
 title: Project setup and best practices
-description: Testing, packaging, and code quality best practices for your Python project.
+description: Testing, packaging, and code-quality best practices for your Python project.
 ---
 
 # Best practices for your project
@@ -12,20 +12,20 @@ This page covers licensing, packaging, testing, and documenting your project,
 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 polished it up, consider adding your project to the [Qiskit
+Once you've put the finishing touches on it, consider adding your project to the [Qiskit
 ecosystem](https://www.ibm.com/quantum/ecosystem).
 
 ## GitHub
 
 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
+hosting platform. GitHub is based on [Git](https://git-scm.com/), a version
+control system. It provides a large set of tools to collaborate and
+maintain high quality. See [Github
 skills](https://skills.github.com/) to get up to speed on GitHub quickly.
 
 Some key features are:
 
-* **Issues and Pull requests**
+* **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
@@ -41,7 +41,7 @@ Some key features are:
 
   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
+  code or automatically [publish your package](#package-your-project) when
   you tag a commit.
 
 * **Security features**
@@ -57,7 +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.
+The rest of this page will assume you have your project hosted on GitHub, although
+you are welcome to other providers like GitLab.
 
 ## Choose a license
 
@@ -66,7 +67,7 @@ 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.
+best for you, and consider seeking legal help.
 
 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
@@ -74,6 +75,7 @@ automatically add a standard license.
 
 ## Dependency management
 
+Most projects depend on other projects, such as Qiskit or NumPy.
 If you don't clearly specify your project's dependencies, users (including your
 future self) will struggle to install and use it.
 
@@ -118,15 +120,21 @@ The two most popular testing frameworks in Python are:
 * 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.
+project against different versions of Python. Tox [is compatible](https://python-poetry.org/docs/faq/#is-tox-supported) with Poetry.
 
 ## Code quality tools
 
 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
+your code. Formatters will auto-format your code to use a consistent style.
+
+A popular linter for Python is
+[`ruff`](https://docs.astral.sh/ruff/), which also
+includes a formatter (based on the popular tool [Black](https://black.readthedocs.io/en/stable/)).
+Other popular tools include
 [`mypy`](https://www.mypy-lang.org/) for type-checking, and
 [`bandit`](https://bandit.readthedocs.io/en/latest/) for security scanning.
 
-Once you've set your tools up, you can use a [GitHub action](#github) to make
+Once you've set up your tools, you can use a [GitHub action](#github) to make
 sure all code pushed to your repository has been linted.
+
+Document how to run the linters and formatters in your README.md or CONTRIBUTOR.md.

From a7d02c71e9654a649f35aeaabe71a0a97ec4c85f Mon Sep 17 00:00:00 2001
From: Frank Harkins <frankharkins@hotmail.co.uk>
Date: Thu, 10 Oct 2024 11:12:18 +0100
Subject: [PATCH 8/9] Mention CI/CD

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
---
 docs/open-source/best-practices.mdx | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/open-source/best-practices.mdx b/docs/open-source/best-practices.mdx
index 71fea8b69c6..7c04aa1e8f5 100644
--- a/docs/open-source/best-practices.mdx
+++ b/docs/open-source/best-practices.mdx
@@ -39,10 +39,16 @@ Some key features are:
 
 * **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 [publish your package](#package-your-project) when
-  you tag a commit.
+  This feature runs scripts in the cloud 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 [publish your
+  package](#package-your-project) when you tag a commit.
+
+  Use GitHub actions for [continuous
+  integration](https://www.atlassian.com/continuous-delivery/continuous-integration)
+  (CI) and [continuous
+  deployment](https://www.ibm.com/topics/continuous-deployment) (CD) of your
+  project.
 
 * **Security features**
 

From f6977d87db205fb945f3e74b4c2d0389e489ac2b Mon Sep 17 00:00:00 2001
From: Frank Harkins <frankharkins@hotmail.co.uk>
Date: Thu, 10 Oct 2024 11:28:10 +0100
Subject: [PATCH 9/9] Elaborate on requirements

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
---
 docs/open-source/best-practices.mdx | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/docs/open-source/best-practices.mdx b/docs/open-source/best-practices.mdx
index 7c04aa1e8f5..20a7ae18431 100644
--- a/docs/open-source/best-practices.mdx
+++ b/docs/open-source/best-practices.mdx
@@ -81,21 +81,24 @@ automatically add a standard license.
 
 ## Dependency management
 
-Most projects depend on other projects, such as Qiskit or NumPy.
-If you don't clearly specify your project's dependencies, users (including your
-future self) will struggle to install and use it.
+Most projects depend on other projects, such as Qiskit or NumPy. 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.
+file in your repository. You may also see `requirements-dev.txt` for
+dependencies only used for contributing to the project, such as linters or test
+runners. You must manually identify your requirements and keep requirements
+files up to date.
+
+Tools such as [Poetry](https://python-poetry.org/) manage dependencies for you
+and keep track of everything you've installed. Installing a dependency through
+Poetry will add it to a "lockfile", which stores the exact versions of each
+package needed to replicate your environment. Without a lockfile, future users
+may try to run your project with more recent versions of your dependencies,
+with which it might not work correctly.
 
 See [Poetry: Basic usage](https://python-poetry.org/docs/basic-usage/) to set
 up your project with Poetry.