From fd742230502e0055ac98686a298fe926fe2b958a Mon Sep 17 00:00:00 2001 From: Jake Lishman Date: Mon, 24 Jan 2022 13:53:48 +0000 Subject: [PATCH] Add section on requirements to CONTRIBUTING --- CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 074023efb412..48486e66373d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,10 @@ contributing to terra, these are documented below. * [Branches](#branches) * [Release Cycle](#release-cycle) * [Adding deprecation warnings](#adding-deprecation-warnings) +* [Using dependencies](#using-dependencies) + * [Adding a requirement](#adding-a-requirement) + * [Adding an optional dependency](#adding-an-optional-dependency) + * [Checking for optionals](#checking-for-optionals) * [Dealing with git blame ignore list](#dealing-with-the-git-blame-ignore-list) ### Choose an issue to work on @@ -478,6 +482,37 @@ def test_method2(self): `test_method1_deprecated` can be removed after `Obj.method1` is removed (following the [Qiskit Deprecation Policy](https://qiskit.org/documentation/contributing_to_qiskit.html#deprecation-policy)). +## Using dependencies + +We distinguish between "requirements" and "optional dependencies" in qiskit-terra. +A requirement is a package that is absolutely necessary for core functionality in qiskit-terra, such as Numpy or Scipy. +An optional dependency is a package that is used for specialized functionality, which might not be needed by all users. +If a new feature has a new dependency, it is almost certainly optional. + +### Adding a requirement + +Any new requirement must have broad system support; it needs to be supported on all the Python versions and operating systems that qiskit-terra supports. +It also cannot impose many version restrictions on other packages. +Users often install qiskit-terra into virtual environments with many different packages in, and we need to ensure that neither we, nor any of our requirements, conflict with their other packages. +When adding a new requirement, you must add it to [`requirements.txt`](requirements.txt) with as loose a constraint on the allowed versions as possible. + +### Adding an optional dependency + +New features can also use optional dependencies, which might be used only in very limited parts of qiskit-terra. +These are not required to use the rest of the package, and so should not be added to `requirements.txt`. +Instead, if several optional dependencies are grouped together to provide one feature, you can consider adding an "extra" to the package metadata, such as the `visualization` extra that installs Matplotlib and Seaborn (amongst others). +To do this, modify the [`setup.py`](setup.py) file, adding another entry in the `extras_require` keyword argument to `setup()` at the bottom of the file. +You do not need to be quite as accepting of all versions here, but it is still a good idea to be as permissive as you possibly can be. +You should also add a new "tester" to [`qiskit.utils.optionals`](qiskit/utils/optionals.py), for use in the next section. + +### Checking for optionals + +You cannot `import` an optional dependency at the top of a file, because if it is not installed, it will raise an error and qiskit-terra will be unusable. +We also largely want to avoid importing packages until they are actually used; if we import a lot of packages during `import qiskit`, it becomes sluggish for the user if they have a large environment. +Instead, you should use [one of the "lazy testers" for optional dependencies](https://qiskit.org/documentation/apidoc/utils.html#module-qiskit.utils.optionals), and import your optional dependency inside the function or class that uses it, as in the examples within that link. +Very lightweight _requirements_ can be imported at the tops of files, but even this should be limited; it's always ok to `import numpy`, but Scipy modules are relatively heavy, so only import them within functions that use them. + + ## Dealing with the git blame ignore list In the qiskit-terra repository we maintain a list of commits for git blame