Skip to content

Commit 94743f9

Browse files
committed
Clarify the Internet part
Clarify the "do not use the Internet" part to make it clearer that we're talking about backend actions, and custom build scripts in particular. We're not talking of Python dependencies that are fetched and installed by frontends. Also, reflow the text to be more logical.
1 parent 0eb407c commit 94743f9

File tree

1 file changed

+26
-14
lines changed

1 file changed

+26
-14
lines changed

source/discussions/downstream-packaging.rst

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -136,9 +136,12 @@ Why?
136136
~~~~
137137

138138
Downstream builds are frequently done in sandboxed environments that cannot
139-
access the Internet. Even if this is not the case, and assuming that you took
140-
sufficient care to properly authenticate downloads, using the Internet
141-
is discouraged for a number of reasons:
139+
access the Internet. The package sources are unpacked into this environment,
140+
and all the necessary dependencies are installed.
141+
142+
Even if this is not the case, and assuming that you took sufficient care to
143+
properly authenticate downloads, using the Internet is discouraged for a number
144+
of reasons:
142145

143146
- The Internet connection may be unstable (e.g. due to poor reception)
144147
or suffer from temporary problems that could cause the process to fail
@@ -159,22 +162,31 @@ is discouraged for a number of reasons:
159162
How?
160163
~~~~
161164

162-
Your source distribution should either include all the files needed
163-
for the package to build, or allow provisioning them externally. Ideally,
164-
it should not even attempt to access the Internet at all, unless explicitly
165-
requested to. If that is not possible to achieve, the next best thing
166-
is to provide an opt-out switch to disable all Internet access.
165+
If the package is implementing any custom build *backend* actions that use
166+
the Internet, for example by automatically downloading vendored dependencies
167+
or fetching Git submodules, its source distribution should either include all
168+
of these files or allow provisioning them externally, and the Internet must not
169+
be used if the files are already present.
170+
171+
Note that this point does not apply to Python dependencies that are specified
172+
in the package metadata, and are fetched during the build and installation
173+
process by *frontends* (such as :ref:`build` or :ref:`pip`). Downstreams use
174+
frontends that use local provisioning for Python dependencies.
167175

168-
When such a switch is used, the build process should fail if some
169-
of the required files are missing, rather than try to fetch them automatically.
170-
This could be done e.g. by checking whether a ``NO_NETWORK`` environment
171-
variable is set to a non-empty value. Please also remember that if you are
172-
fetching remote resources, you must *verify their authenticity* (usually against
173-
a hash), to protect against the file being substituted by a malicious party.
176+
Ideally, custom build scripts should not even attempt to access the Internet
177+
at all, unless explicitly requested to. If any resources are missing and need
178+
to be fetched, they should ask the user for permission first. If that is not
179+
feasible, the next best thing is to provide an opt-out switch to disable
180+
all Internet access. This could be done e.g. by checking whether
181+
a ``NO_NETWORK`` environment variable is set to a non-empty value.
174182

175183
Since downstreams frequently also run tests and build documentation, the above
176184
should ideally extend to these processes as well.
177185

186+
Please also remember that if you are fetching remote resources, you absolutely
187+
must *verify their authenticity* (usually against a hash), to protect against
188+
the file being substituted by a malicious party.
189+
178190

179191
.. _support-system-dependencies-in-builds:
180192

0 commit comments

Comments
 (0)