
Change Log
**********

The following is a log of all user-facing changes to Stem, both
released and unreleased. For a monthly report on work being done see
my development log.

* *Versioning*

* *Unreleased*

* *Version 1.4*

* *Version 1.3*

* *Version 1.2*

* *Version 1.1*

* *Version 1.0*


Versioning
==========

Stem uses semantic versioning, which means that **versions consist of
three numbers** (such as '**1.2.4**'). These are used to convey the
kind of backward compatibility a release has...

   * The first value is the **major version**. This changes
     infrequently, and indicates that backward incompatible changes
     have been made (such as the removal of deprecated functions).

   * The second value is the **minor version**. This is the most
     common kind of release, and denotes that the improvements are
     backward compatible.

   * The third value is the **patch version**. When a Stem release has
     a major issue another release is made which fixes just that
     problem. These do not contain substantial improvements or new
     features. This value is sometimes left off to indicate all
     releases with a given major/minor version.


Unreleased
==========

The following are only available within Stem's git repository.


Version 1.4 (May 13th, 2015)
============================

Stem's 1.4 release brings with it new hidden service capabilities.
Most notably, ephemeral hidden services and the ability to read hidden
service descriptors. This release also changes descriptor validation
to now be opt-in rather than opt-out. When unvalidated content is
lazy-loaded, greatly improving our performance.

And last, Stem also now runs directly under both python2 and python3
without a 2to3 conversion (ticket 14075)!

   * **Controller**

      * Added "Controller" methods for a new style of hidden services
        that don't touch disk: "list_ephemeral_hidden_services()",
        "create_ephemeral_hidden_service()", and
        "remove_ephemeral_hidden_service()" (spec)

      * Added "get_hidden_service_descriptor()" and support for
        HS_DESC_CONTENT events (ticket 14847, spec)

      * "launch_tor_with_config()" avoids writing a temporary torrc to
        disk if able (ticket 13865)

      * "CircuitEvent" support for the new SOCKS_USERNAME and
        SOCKS_PASSWORD arguments (ticket 14555, spec)

      * The 'strict' argument of "can_exit_to()" didn't behave as
        documented (ticket 14314)

      * Threads spawned for status change listeners were never joined
        on, potentially causing noise during interpreter shutdown

      * Added support for specifying the authentication type and
        client names in "create_hidden_service()" (ticket 14320)

   * **Descriptors**

      * Lazy-loading descriptors, improving performance by 25-70%
        depending on what type it is (ticket 14011)

      * Added support for hidden service descriptors (ticket 15004)

      * When reading sanitised bridge descriptors (server or
        extrainfo), "parse_file()" treated the whole file as a single
        descriptor

      * The "DirectoryAuthority" 'fingerprint' attribute was actually
        its 'v3ident'

      * Added consensus' new package attribute (spec)

      * Added extra info' new hs_stats_end, hs_rend_cells,
        hs_rend_cells_attr, hs_dir_onions_seen, and
        hs_dir_onions_seen_attr attributes (spec)

      * Updating Faravahar's address (ticket 14487)

   * **Utilities**

      * Windows support for connection resolution (ticket 14844)

      * "stem.util.connection.port_usage()" always returned None
        (ticket 14046)

      * "stylistic_issues()" and "pyflakes_issues()" now provide
        namedtuples that also includes the line

      * Added "stem.util.system.tail()"

      * Proc connection resolution could fail on especially busy
        systems (ticket 14048)

   * **Website**

      * Added support and instructions for tox (ticket 14091)

      * Added OSX to our download page (ticket 8588)

      * Updated our twitter example to work with the service's 1.1 API
        (ticket 9003)

   * **Version 1.4.1** (May 18th, 2015) - fixed issue where
     descriptors couldn't be unpickled (ticket 16054) and a parsing
     issue for router status entry bandwidth lines (ticket 16048)


Version 1.3 (December 22nd, 2014)
=================================

With Stem's 1.3 release it's now much easier to work with hidden
services, 40% faster to read decriptors, and includes a myriad of
other improvements. For a nice description of the changes this brings
see Nathan Willis' LWN article.

   * **Controller**

      * Added "Controller" methods to more easily work with hidden
        service configurations: "get_hidden_service_conf()",
        "set_hidden_service_conf()", "create_hidden_service()", and
        "remove_hidden_service()" (ticket 12533)

      * Added "get_accounting_stats()" to the "Controller"

      * Added "get_effective_rate()" to the "Controller"

      * Added "connection_time()" to the "BaseController"

      * Changed "get_microdescriptor()", "get_server_descriptor()",
        and "get_network_status()" to get our own descriptor if no
        fingerprint or nickname is provided.

      * Added "ExitPolicy" methods for more easily handling 'private'
        policies (the default prefix) and the defaultly appended
        suffix. This includes "has_private()", "strip_private()",
        "has_default()", and "strip_default()" "ExitPolicy" methods in
        addition to "is_private()" and "is_default()" for the
        "ExitPolicyRule". (ticket 10107)

      * Added the reason attribute to the "HSDescEvent" (spec)

      * "launch_tor_with_config()" could cause a "Too many open files"
        OSError if called too many times (ticket 13141)

      * The "get_exit_policy()" method errored if tor couldn't
        determine our external address

      * The Controller's methods for retrieving descriptors could
        raise unexpected ValueErrors if tor didn't have any
        descriptors available

      * Throwing a new "DescriptorUnavailable" exception type when the
        "Controller" can't provide the descriptor for a relay (ticket
        13879)

   * **Descriptors**

      * Improved speed for parsing consensus documents by around 40%
        (ticket 12859 and ticket 13821)

      * Don't fail if consensus method 1 is not present, as it is no
        longer required (spec)

      * Include '*.new' files when reading from a Tor data directory
        (ticket 13756)

      * Updated the authorities we list, replacing turtles with
        longclaw and updating gabelmoo's address

      * Noting if authorities are also a bandwidth authority or not

      * Microdescriptor validation issues could result in an
        AttributeError (ticket 13904)

   * **Utilities**

      * Added support for directories to
        "stem.util.conf.Config.load()"

      * Changed "stem.util.conf.uses_settings()" to only provide a
        'config' keyword arument if the decorated function would
        accept it

      * Added "stem.util.str_tools.crop()"

      * Added "stem.util.proc.file_descriptors_used()"

      * Dropped the 'get_*' prefix from most function names. Old names
        will still work, but are a deprecated alias.

   * **Interpreter**

      * The /info command errored for relays without contact
        information

   * **Website**

      * Tutorial for hidden services

      * Example for writing descriptors to disk and reading them back
        (ticket 13774)

      * Added Gentoo to our download page and handful of testing
        revisions for that platform (ticket 13904)

      * Tests for our tutorial examples (ticket 11335)

      * Revised GitWeb urls to work after its upgrade


Version 1.2 (June 1st, 2014)
============================

Stem release 1.2 added our interactive Tor interpreter among numerous
other improvements and fixes.

   * **Controller**

      * New, better "connect()" function that deprecates
        "connect_port()" and "connect_socket_file()"

      * Added "is_newnym_available()" and "get_newnym_wait()" methods
        to the "Controller"

      * Added "get_ports()" and "get_listeners()" methods to the
        "Controller"

      * Added "drop_guards()" (ticket 10032, spec)

      * Added the id attribute to the "ORConnEvent" (spec)

      * Added support for CONN_BW events (spec)

      * Added support for CIRC_BW events (spec)

      * Added support for CELL_STATS events (spec)

      * Added support for TB_EMPTY events (spec)

      * Added support for HS_DESC events (ticket 10807, spec)

      * Changed "get_network_status()" and "get_network_statuses()" to
        provide "RouterStatusEntryMicroV3" if Tor is using
        microdescriptors (ticket 7646)

      * The "connect_port()" and "connect_socket_file()" didn't
        properly mark the Controller it returned as being
        authenticated, causing event listening among other things to
        fail

      * The "add_event_listener()" method couldn't accept event types
        that Stem didn't already recognize

      * The "ExitPolicy" class couldn't be pickled

      * Tor instances spawned with "launch_tor()" and
        "launch_tor_with_config()" could hang due to unread stdout
        content, we now close stdout and stderr once tor finishes
        bootstrapping (ticket 9862)

   * **Descriptors**

      * Added tarfile support to "parse_file()" (ticket 10977)

      * Added microdescriptor's new identifier and identifier_type
        attributes (spec)

   * **Utilities**

      * Added the stem.util.test_tools module

      * Started vending the stem.util.tor_tools module

      * Added "stem.util.connection.port_usage()"

      * Added "stem.util.system.files_with_suffix()"

   * **Interpreter**

      * Initial release of our interactive Tor interpreter!

   * **Website**

      * Added a section with example scripts.

      * Made FAQ and other sections quite a bit more succinct.

   * **Version 1.2.2** (June 7th, 2014) - fixed an issue where the
     stem.util.conf module would fail under Python 2.6 with an
     AttributeError (ticket 12223)

   * **Version 1.2.1** (June 3rd, 2014) - fixed an issue where
     descriptor parsersing would fail under Python 3.x with a
     TypeError (ticket 12185)


Version 1.1 (October 14th, 2013)
================================

Stem release 1.1 introduced remote descriptor fetching, connection
resolution and a myriad of smaller improvements and fixes.

   * **Controller**

      * "get_network_status()" and "get_network_statuses()" now
        provide v3 rather than v2 directory information (ticket 7953,
        spec)

      * "AddrMapEvent" support for the new CACHED argument (ticket
        8596, spec)

      * "attach_stream()" could encounter an undocumented 555 response
        (ticket 8701, spec)

      * "RelayDescriptor" digest validation was broken when dealing
        with non-unicode content with Python 3 (ticket 8755)

      * The "Controller" use of cached content wasn't thread safe
        (ticket 8607)

      * Added "get_user()" method to the "Controller"

      * Added "get_pid()" method to the "Controller"

      * "StreamEvent" didn't recognize IPv6 addresses (ticket 9181)

      * "get_conf()" mistakenly cached hidden service related options
        (ticket 9792)

      * Added support for TRANSPORT_LAUNCHED events (spec)

   * **Descriptors**

      * Added the stem.descriptor.remote module.

      * Added support for TorDNSEL exit lists (ticket 8255)

      * The "DescriptorReader" mishandled relative paths (ticket 8815)

   * **Utilities**

      * Connection resolution via the "get_connections()" function
        (ticket 7910)

      * "set_process_name()" inserted spaces between characters
        (ticket 8631)

      * "pid_by_name()" can now pull for all processes with a given
        name

      * "call()" ignored the subprocess' exit status

      * Added "stem.util.system.name_by_pid()"

      * Added "stem.util.system.user()"

      * Added "stem.util.system.start_time()"

      * Added "stem.util.system.bsd_jail_path()"

      * Added "stem.util.system.is_tarfile()"

      * Added "stem.util.connection.is_private_address()"

   * **Website**

      * Overhaul of Stem's download page. This included several
        improvements, most notably the addition of PyPI, Ubuntu,
        Fedora, Slackware, and FreeBSD.

      * Replaced default sphinx header with a navbar menu.

      * Added this change log.

      * Added the FAQ page.

      * Settled on a logo for Stem.

      * Expanded the client usage tutorial to cover SocksiPy and
        include an example for polling Twitter.

      * Subtler buttons for the frontpage (before and after).

   * **Version 1.1.1** (November 9th, 2013) - fixed an issue where
     imports of stem.util.system would fail with an ImportError for
     pwd under Windows (ticket 10072)


Version 1.0 (March 26th, 2013)
==============================

This was the initial release of Stem.

   * **Version 1.0.1** (March 27th, 2013) - fixed an issue where
     installing with Python 3.x (python3 setup.py install) resulted in
     a stacktrace
