1 files changed, 77 insertions, 0 deletions
diff --git a/doc/upload.rst b/doc/upload.rst
new file mode 100644
index 0000000..df5af5e
--- /dev/null
+++ b/doc/upload.rst
@@ -0,0 +1,77 @@
+Controlling package uploads
+===========================
+
+.. program:: flit publish
+
+The command ``flit publish`` will upload your package to a package index server.
+The default settings let you upload to `PyPI <https://pypi.org/>`_,
+the default Python Package Index, with a single user account.
+
+If you want to upload to other servers, or with more than one user account,
+or upload packages from a continuous integration job,
+you can configure Flit in two main ways:
+
+Using .pypirc
+-------------
+
+You can create or edit a config file in your home directory, ``~/.pypirc`` that
+will be used by default or you can specify a custom location.
+This is also used by other Python tools such as `twine
+<https://pypi.python.org/pypi/twine>`_.
+
+For instance, to upload a package to the `Test PyPI server <https://test.pypi.org/>`_
+instead of the normal PyPI, use a config file looking like this:
+
+.. code-block:: ini
+
+    [distutils]
+    index-servers =
+       pypi
+       testpypi
+
+    [pypi]
+    repository = https://upload.pypi.org/legacy/
+    username = sirrobin  # Replace with your PyPI username
+
+    [testpypi]
+    repository = https://test.pypi.org/legacy/
+    username = sirrobin  # Replace with your TestPyPI username
+
+You can select an index server from this config file with the
+:option:`--repository` option::
+
+    flit publish --repository testpypi
+
+If you don't use this option,
+Flit will use the server called ``pypi`` in the config file. If that doesn't
+exist, it uploads to PyPI at ``https://upload.pypi.org/legacy/`` by default.
+
+If you publish a package and you don't have a ``.pypirc`` file, Flit will create
+it to store your username.
+
+Flit tries to store your password securely using the
+`keyring <https://pypi.python.org/pypi/keyring>`_ library.
+If keyring is not installed, Flit will ask for your password for each upload.
+Alternatively, you can also manually add your password to the ``.pypirc`` file
+(``password = ...``)
+
+.. _upload_envvars:
+
+Using environment variables
+---------------------------
+
+You can specify a server to upload to with :envvar:`FLIT_INDEX_URL`, and
+pass credentials with :envvar:`FLIT_USERNAME` and :envvar:`FLIT_PASSWORD`.
+Environment variables take precedence over the config file, except if you use
+the :option:`--repository` option to explicitly pick a server from the config file.
+
+This can make it easier to automate uploads, for example to release packages
+from a continuous integration job.
+
+.. warning::
+
+   Storing a password in an environment variable is convenient, but it's
+   `easy to accidentally leak it <https://www.diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/>`_.
+   Look out for scripts that helpfully print all environment variables for
+   debugging, and remember that other scripts and libraries you run in
+   that environment have access to your password.