[tor-commits] [stem/master] Descriptor tutorial section for 'Where do descriptors come from?'

[atagar at torproject.org]

commit aa4e1bbb909c502cad7c824912d18282f9e35ae9
Author: Damian Johnson <atagar at torproject.org>
Date:   Fri May 15 09:59:00 2015 -0700

    Descriptor tutorial section for 'Where do descriptors come from?'
    
    Jordan Wright's recent article gives a great excuse to add a little section on
    this. :P
    
      https://jordan-wright.github.io/blog/2015/05/14/how-tor-works-part-three-the-consensus/
      https://jordan-wright.github.io/images/blog/how_tor_works/consensus.png
---
 docs/tutorials/mirror_mirror_on_the_wall.rst |   26 ++++++++++++++++++++++++++
 stem/__init__.py                             |    2 +-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst
index bec30a7..9ef620f 100644
--- a/docs/tutorials/mirror_mirror_on_the_wall.rst
+++ b/docs/tutorials/mirror_mirror_on_the_wall.rst
@@ -5,6 +5,7 @@ The following is an overview of **Tor descriptors**. If you're already familiar
 with what they are and where to get them then you may want to skip to the end.
 
 * :ref:`what-is-a-descriptor`
+* :ref:`where-do-descriptors-come-from`
 * :ref:`where-can-i-get-the-current-descriptors`
 * :ref:`where-can-i-get-past-descriptors`
 * :ref:`can-i-get-descriptors-from-the-tor-process`
@@ -34,6 +35,31 @@ Descriptor Type
 `Hidden Service Descriptor <../api/descriptor/hidden_service_descriptor.html>`_  Information pertaining to a `Hidden Service <https://www.torproject.org/docs/hidden-services.html.en>`_. These can only be `queried through the tor process <over_the_river.html#hidden-service-descriptors>`_.
 ================================================================================ ===========
 
+.. _where-do-descriptors-come-from:
+
+Where do descriptors come from?
+-------------------------------
+
+Descriptors fall into two camps:
+
+* **Server**, **extra-info**, and **hidden service** descriptors are
+  **self-published documents**. Relays and hidden services publish these about
+  themselves, and so naturally can indicate anything they'd like in them (true
+  or not).
+  
+  These are **self contained documents**, bundling within themselves a
+  signiture Stem can `optionally check
+  <./mirror_mirror_on_the_wall.html#validating-the-descriptors-content>`_.
+
+* **Network status documents** (aka **votes**, the **consensus**, and **router
+  status entries** they contain) are created by the **directory authorities**.
+  For a great overview on how this works see `Jordan Wright's article on how
+  the consensus is made
+  <https://jordan-wright.github.io/blog/2015/05/14/how-tor-works-part-three-the-consensus/>`_.
+
+**Microdescriptors** are merely a distilled copy of a **server descriptor**,
+and so belong to the first camp.
+
 .. _where-can-i-get-the-current-descriptors:
 
 Where can I get the current descriptors?
diff --git a/stem/__init__.py b/stem/__init__.py
index 5134c2f..7229453 100644
--- a/stem/__init__.py
+++ b/stem/__init__.py
@@ -441,7 +441,7 @@ Library for working with the tor process.
   ================= ===========
 """
 
-__version__ = '1.4.0'
+__version__ = '1.4.0-dev'
 __author__ = 'Damian Johnson'
 __contact__ = 'atagar at torproject.org'
 __url__ = 'https://stem.torproject.org/'