Add security and feed information to docs

Ref. pypi#1323
brainwane · Mar 8, 2018 · 4a7338a · 4a7338a
1 parent 42b3ccd
commit 4a7338a
Show file tree

Hide file tree

Showing 4 changed files with 29 additions and 1 deletion.
diff --git a/docs/api-reference/feeds.rst b/docs/api-reference/feeds.rst
@@ -2,7 +2,7 @@ Feeds
 =====
 
 PyPI offers two RSS feeds, the `Newest Packages Feed`_ and the `Latest Updates
-Feed`_.
+Feed`_. You can also call its APIs to get more details on project activity.
 
 
 Newest Packages Feed
@@ -19,3 +19,22 @@ Latest Updates Feed
 Available at https://pypi.org/rss/updates.xml, this feed provides the latest
 newly created releases for individual projects on PyPI, including the project
 name and description, release version, and a link to the release page.
+
+Project and release activity details
+------------------------------------
+
+PyPI publishes a "journal" of all project, package, and release
+activity (including release deletions). You can query it with a mix of
+:ref:`changelog-since` and :ref:`simple-api`. Call
+``changelog_last_serial()`` (in :doc:`xml-rpc`) to get the current
+revision of the journal (the last event's serial ID), then look at
+``/simple/`` to get a list of all packages that currently
+exist. Subsequently, you can call
+``changelog_since_serial(since_serial)`` with the serial ID you
+retrieved, and get the list of all actions that have occurred since
+then.
+
+You could also request ``GET /simple/``, and record the ``ETag``, and
+then periodically do a conditional HTTP GET to ``/simple/`` with that
+ETag included. A 200 OK response indicates something has been added or
+removed; if you get a 304 Not Modified, then nothing has changed.
diff --git a/docs/api-reference/legacy.rst b/docs/api-reference/legacy.rst
@@ -4,6 +4,7 @@ Legacy API
 The "Legacy API" provides feature parity with `pypi-legacy`_, hence the term
 "legacy".
 
+.. _simple-api:
 
 Simple Project API
 ------------------

diff --git a/docs/api-reference/xml-rpc.rst b/docs/api-reference/xml-rpc.rst
@@ -159,6 +159,7 @@ Package Querying
   since the given timestamp. The packages will be listed in descending date
   of most recent change.
 
+.. _changelog-since:
 
 Mirroring Support
 -----------------

diff --git a/docs/security.rst b/docs/security.rst
@@ -3,7 +3,14 @@
 Security
 ========
 
+Security policy
+---------------
 To read the most up to date version of our security policy, please visit
 the application security page, available via the site_ footer.
 
+Project and release activity details
+------------------------------------
+Please see :doc:`api-reference/feeds` for how to track new and updated
+releases on PyPI.
+
 .. _site: https://pypi.org