Add "Project best practices" page #1760
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…H/ecosystem-best-practices
Comment on lines
+21
to
+23
| 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 |
There was a problem hiding this comment.
Suggested change
| 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 |
| 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** |
There was a problem hiding this comment.
Suggested change
| * **GitHub actions** | |
| * **GitHub actions** |
| conduct](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project). | ||
|
|
||
| * **GitHub actions** | ||
|
|
There was a problem hiding this comment.
Suggested change
| Software projects benefit from using continuous integration (CI) and continuous deployment (CD): | |
| * [Continuous integration](https://www.atlassian.com/continuous-delivery/continuous-integration): automating the integration of changes to your code, including through the use of automated tests to ensure your changes do not break the project. | |
| * [Continuous deployment](https://www.ibm.com/topics/continuous-deployment): automation of your deployment/release process. Often, continuous deployment can be semi-automated, such as requiring a human to initiate the deployment. |
|
|
||
| * **GitHub actions** | ||
|
|
||
| This feature runs scripts when certain events happen in your GitHub repo. For |
There was a problem hiding this comment.
Suggested change
| This feature runs scripts when certain events happen in your GitHub repo. For | |
| GitHub Actions allows you to use both CI and CD in your project by providing | |
| you a free cloud-based runner to run scripts and tests when certain events | |
| happen in your GitHub repo, such as opening a pull request. For |
| – 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. |
There was a problem hiding this comment.
Suggested change
| 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. |
There was a problem hiding this comment.
Suggested change
| 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 use other providers like GitLab. |
| * 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. |
There was a problem hiding this comment.
Suggested change
| project against different versions of Python. | |
| project against different versions of Python. Tox | |
| [can be used](https://python-poetry.org/docs/faq/#is-tox-supported) with Poetry. |
There was a problem hiding this comment.
Consider instead "Tox is compatible with Poetry" to avoid passive voice
| [`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 | ||
| sure all code pushed to your repository has been linted. |
There was a problem hiding this comment.
Suggested change
| sure all code pushed to your repository has been linted. | |
| 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. |
Comment on lines
+125
to
+129
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| A linter is a tool that detects (and sometimes corrects) common problems in | |
| 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. |
Comment on lines
+80
to
+90
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| Traditionally, many Python projects use a `requirements.txt` file to list the project's dependencies. | |
| You may also see `requirements-dev.txt` to list dependencies only used for contributing to | |
| the project, such as linters or test runners. This approach can be fine, but it has two issues: | |
| 1) no "lockfiles", and 2) you still need to set up metadata about your project. | |
| Instead of the traditional requirements.txt approach, build tools such as [Poetry](https://python-poetry.org/) improve dependency management. Poetry also ensures that you properly set up metadata for your project, | |
| such as which Python versions you support; this metadata is necessary to | |
| [package your project](#package-your-project). | |
| Installing a dependency through Poetry will add it to a "lockfile", | |
| which keeps track of the exact versions of each package you have | |
| installed. Lockfiles are crucial for | |
| ["supply chain security"](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security). | |
| Lockfiles also ensure that your project will not break overnight due to new releases of dependencies | |
| breaking your project; with a lockfile, your dependencies will only change when you intentionally upgrade. |
There was a problem hiding this comment.
@Eric-Arellano Is it important to put "supply chain security" in quotes? I'd leave them off unless it's confusing otherwise.
|
|
||
| ## Dependency management | ||
|
|
||
| If you don't clearly specify your project's dependencies, users (including your |
There was a problem hiding this comment.
Suggested change
| If you don't clearly specify your project's dependencies, users (including your | |
| Most projects depend on other projects, such as Qiskit or NumPy. | |
| If you don't clearly specify your project's dependencies, users (including your |
abbycross
reviewed
Sep 3, 2024
| @@ -39,6 +39,15 @@ | |||
| "url": "https://github.com/Qiskit/qiskit/blob/main/MAINTAINING.md" | |||
| } | |||
| ] | |||
| }, | |||
| { | |||
| "title": "Creating a Qiskit-based project", | |||
There was a problem hiding this comment.
Suggested change
| "title": "Creating a Qiskit-based project", | |
| "title": "Create a Qiskit-based project", |
Sometimes it feels awkward to do so but we try to avoid -ing in titles for consistency and to clearly suggest action
abbycross
reviewed
Sep 3, 2024
| @@ -0,0 +1,132 @@ | |||
| --- | |||
| title: Project setup and best practices | |||
| description: Testing, packaging, and code quality best practices for your Python project. | |||
There was a problem hiding this comment.
Suggested change
| description: Testing, packaging, and code quality best practices for your Python project. | |
| description: Testing, packaging, and code-quality best practices for your Python project. |
abbycross
reviewed
Sep 3, 2024
| 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 |
There was a problem hiding this comment.
Suggested change
| 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 |
abbycross
reviewed
Sep 3, 2024
|
|
||
| Some key features are: | ||
|
|
||
| * **Issues and Pull requests** |
There was a problem hiding this comment.
Suggested change
| * **Issues and Pull requests** | |
| * **Issues and pull requests** |
abbycross
reviewed
Sep 3, 2024
|
|
||
| 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 |
There was a problem hiding this comment.
Suggested change
| code or automatically [publishing your package](#package-your-project) when | |
| code or automatically [publish your package](#package-your-project) when |
abbycross
reviewed
Sep 3, 2024
| [`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 |
There was a problem hiding this comment.
Suggested change
| 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 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds a new page on best practices for ecosystem projects.
Link to preview