diff --git a/ChangeLog b/ChangeLog deleted file mode 100644 index 82cf7ac0..00000000 --- a/ChangeLog +++ /dev/null @@ -1,5 +0,0 @@ - -2018-04-30 v0.0.1 - -* Initial release to support the Mitogen extension for Ansible. - diff --git a/docs/changelog.rst b/docs/changelog.rst index cbd8c2cd..fb3599b4 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,6 +1,120 @@ -Change Log ----------- +Release Notes +============= -.. literalinclude:: ../ChangeLog - :language: none + +.. raw:: html + + + + +v0.2.0 (2018-07-08) +------------------- + +Mitogen 0.2.x is the inaugural feature-frozen branch eligible for fixes only, +except for problem areas listed as in-scope below. While stable from a +development perspective, it should still be considered "beta" at least for the +initial releases. + +**In Scope** + +* Python 3.x performance improvements +* Subprocess reaping improvements +* Major documentation improvements +* PyPI/packaging improvements +* Test suite improvements +* Replacement CI system to handle every supported OS +* Minor deviations from vanilla Ansible behaviour + +The goal is a *tick/tock* model where even-numbered series are a maturation of +the previous unstable series, and unstable series are released on PyPI with +``--pre`` enabled. The API and user visible behaviour should remain unchanged +within a stable series. + + +Mitogen for Ansible +~~~~~~~~~~~~~~~~~~~ + +* Support for Ansible 2.3 - 2.5.x and any mixture of Python 2.6, 2.7 or 3.6 on + controller and target nodes. + +* Drop-in support for many Ansible connection types. + +* Preview of Connection Delegation feature. + +* Built-in file transfer compatible with connection delegation. + + +**Known Issues** + +* Performance does not scale linearly with target count. This requires + significant additional work, as major bottlenecks exist in the surrounding + Ansible code. Performance-related bug reports for any scenario remain + welcome with open arms. + +* Performance on Python 3 is significantly worse than on Python 2. While this + has not yet been investigated, at least some of the regression appears to be + part of the core library, and should therefore be straightforward to fix as + part of 0.2.x. + +* *Module Replacer* style Ansible modules are not supported. + +* Actions are single-threaded for each `(host, user account)` combination, + including actions that execute on the local machine. Certain styles of + playbook may experience slowdown compared to vanilla Ansible if they employ + long-running ``local_action`` or ``delegate_to`` tasks delegating many target + hosts to a single machine and user account. + +* Connection Delegation remains in preview and has bugs around how it infers + connections. Connection establishment will remain single-threaded for the 0.2 + series, however connection inference bugs will be addressed in a future 0.2 + release. + + +Core Library +~~~~~~~~~~~~ + +* Synchronous connection establishment via OpenSSH, sudo, su, Docker, LXC and + FreeBSD Jails, local subprocesses and :func:`os.fork`. Parallel connection + setup is possible using multiple threads. Connections may be used from one or + many threads after establishment. + +* UNIX masters and children, with Linux, MacOS, FreeBSD, NetBSD, OpenBSD and + Windows Subsystem for Linux explicitly supported. + +* Automatic tests covering Python 2.6, 2.7 and 3.6 on Linux only. + + +**Known Issues** + +* Serialization is still based on :mod:`pickle`. While there is high confidence + remote code execution is impossible in Mitogen's configuration, an untrusted + context may at least trigger disproportionately high memory usage injecting + small messages (*"billion laughs attack"*). Replacement is an important + future priority, but not critical for an initial release. + +* Child processes are not reliably reaped, leading to a pileup of zombie + processes when a program makes many short-lived connections in a single + invocation. This does not impact Mitogen for Ansible, however it limits the + usefulness of the core library. A future 0.2 release will address it. + +* Some races remain around :class:`mitogen.core.Broker ` destruction, + disconnection and corresponding file descriptor closure. These are only + problematic in situations where child process reaping is also problematic. + +* The `fakessh` component does not shut down correctly and requires flow + control added to the design. While minimal fixes are possible, due to the + absense of flow control the original design is functionally incomplete. + +* The multi-threaded :ref:`service` remains in a state of design flux and + should be considered obsolete, despite heavy use in Mitogen for Ansible. A + future replacement may be integrated more tightly with, or entirely replace + the RPC dispatcher on the main thread. + +* Documentation is in a state of disrepair. This will be improved over the 0.2 + series. diff --git a/docs/services.rst b/docs/services.rst index 44c49d96..76658be3 100644 --- a/docs/services.rst +++ b/docs/services.rst @@ -1,6 +1,7 @@ .. currentmodule:: mitogen.service +.. _service: Service Framework ================= diff --git a/docs/toc.rst b/docs/toc.rst index 4d817301..fa09b44c 100644 --- a/docs/toc.rst +++ b/docs/toc.rst @@ -12,6 +12,6 @@ Table Of Contents getting_started api examples + changelog internals shame - changelog diff --git a/mitogen/__init__.py b/mitogen/__init__.py index 070cf69e..a4a32cdd 100644 --- a/mitogen/__init__.py +++ b/mitogen/__init__.py @@ -33,7 +33,7 @@ be expected. On the slave, it is built dynamically during startup. #: Library version as a tuple. -__version__ = (0, 0, 2) +__version__ = (0, 1, 0) #: This is :data:`False` in slave contexts. Previously it was used to prevent