Merge branch 'release/8.2.1'

README.md

@@ -39,7 +39,7 @@ purists for maximum longevity), you might start by replicating the library class
 events with pull-based notifications allows the application state to be
 projected accurately into replicas, indexes, view models, and other applications.
 
-**Process and systems** — scalable event processing with application pipelines.Runnable
+**Process and systems** — scalable event processing with application pipelines. Runnable
 with single thread, multiprocessing on a single machine, and in a cluster of machines
 using the actor model. Parallel pipelines are synchronised with causal dependencies.
 
@@ -66,7 +66,7 @@ causation IDs, which allows a story to be traced through a system of application
 
 **Compression** - reduces the size of stored domain events and snapshots, usually
 by around 25% to 50% of the original size. Compression reduces the size of data
-in the database and increases transit time across a network.
+in the database and decreases transit time across a network.
 
 **Application-level encryption** — encrypts and decrypts stored events and snapshots,
 using a cipher strategy passed as an option to the sequenced item mapper. Can be used

docs/topics/features.rst

@@ -20,7 +20,7 @@ purists for maximum longevity), you might start by replicating the library class
 events with pull-based notifications allows the application state to be
 projected accurately into replicas, indexes, view models, and other applications.
 
-**Process and systems** — scalable event processing with application pipelines.Runnable
+**Process and systems** — scalable event processing with application pipelines. Runnable
 with single thread, multiprocessing on a single machine, and in a cluster of machines
 using the actor model. Parallel pipelines are synchronised with causal dependencies.
 
@@ -47,7 +47,7 @@ causation IDs, which allows a story to be traced through a system of application
 
 **Compression** - reduces the size of stored domain events and snapshots, usually
 by around 25% to 50% of the original size. Compression reduces the size of data
-in the database and increases transit time across a network.
+in the database and decreases transit time across a network.
 
 **Application-level encryption** — encrypts and decrypts stored events and snapshots,
 using a cipher strategy passed as an option to the sequenced item mapper. Can be used

docs/topics/installing.rst

@@ -2,14 +2,35 @@
 Installation guide
 ==================
 
-Use pip to install the library from the
+It is recommended always to install into a virtual environment.
+
+You can use pip to install the library from the
 `Python Package Index <https://pypi.org/project/eventsourcing/>`__.
 
 ::
 
     $ pip install eventsourcing
 
 
+Other package installers are available.
+
+To avoid installing future incompatible releases, when including the
+library in a list of project dependencies it is recommended to specify
+at least some of the current version number. Preferences regarding how
+and where to specify versions of project dependencies vary.
+
+::
+
+    eventsourcing<=8.2.99999
+
+As an example, the expression above would install the latest version
+of v8.2.x series of releases, allowing future bug fixes to be installed
+with point version number increments, whilst avoiding any potentially
+destabilising additional features introduced with minor version number
+increments, and also any backwards incompatible changes introduced with
+major verison number increments.
+
+
 Install options
 ===============
 
@@ -22,7 +43,7 @@ later by running the install command again with the options you want.
 SQLAlchemy
 ----------
 
-If you want to use `SQLAlchemy <https://www.sqlalchemy.org/>`__, then install
+If you want to store events using `SQLAlchemy <https://www.sqlalchemy.org/>`__, then install
 the library with the 'sqlalchemy' option.
 
 ::
@@ -46,7 +67,7 @@ about crafting database connection strings for particular database drivers.
 Django
 ------
 
-Similarly, if you want to use `Django <https://www.djangoproject.com/>`__,
+Similarly, if you want to store events using `Django <https://www.djangoproject.com/>`__,
 then please install with the 'django' option.
 
 ::
@@ -61,14 +82,26 @@ that works with `Django and your database system <https://docs.djangoproject.com
 Cassandra
 ---------
 
-If you want to use `Apache Cassandra <http://cassandra.apache.org/>`__,
+If you want to store events using `Apache Cassandra <http://cassandra.apache.org/>`__,
 then please install with the 'cassandra' option.
 
 ::
 
     $ pip install eventsourcing[cassandra]
 
 
+Ray
+---
+
+If you want to run a system of applications with `Ray <https://ray.io/>`__,
+then please install with the 'ray' option.
+
+::
+
+    $ pip install eventsourcing[ray]
+
+
+
 Tests
 -----
 

docs/topics/introduction.rst

@@ -10,26 +10,40 @@ event-sourced application is determined by a sequence of events.
 Another definition has event sourcing as a persistence mechanism
 for domain driven design.
 
+That's the basic story, at least. In practice, because a sequence of
+stored events can be queried in only a limited number of ways, to obtain
+the views of the state of an application that users need when making
+command requests, several other design patterns are needed to develop
+useful software. And several other design patterns are needed to ensure
+reliability, maintainability, and scalability.
+
 
 This library
 ============
 
-This is a library for event sourcing in Python. At its core, this library supports
-storing and retrieving sequences of items, such as the domain events of aggregates
-in a event-sourced domain driven design.
-
-To demonstrate how its persistence mechanism can be used effectively,
-this library documentation has examples of event-sourced applications
-with event-sourced domain models. The library base classes used in these
-examples can be conveniently used to create your own applications.
-A style is suggested for writing event-sourced domain models, and
-event-soured aggregates that have command methods which trigger domain events.
-
-Using this library, it is also possible to define an entire distributed system of
-event-sourced applications independently of infrastructure. That means system
+This is a library for event sourcing in Python. At its core, this library
+supports storing and retrieving sequences of items, such as the domain events
+of event-sourced aggregates in a domain driven design. A variety of schemas
+and technologies can be used for sequencing and storing events, and this
+library supports several of these possibilities.
+
+To demonstrate how storing and retrieving domain events can be used effectively
+as a persistence mechanism in an event-sourced application, this library includes
+base classes for event-sourced domain entities and applications of different kinds.
+An domain model developed using these classes will not depend on infrastructure
+("onion" archictecture). A style is suggested for event-sourced aggregates: to have
+command methods which "trigger" domain events. Triggered domain events are used to
+mutate the state of the aggregate, and then stored. The stored events of an aggregate
+can be retrieved and used to obtain the current state of the aggregate. The stored
+events of an application can also be propagated and used to project the state of
+the application into the materialised views needed by users. Stored events can also
+be processed further by other applications in the same system, and by other systems.
+
+It is also possible to define an entire application, and indeed an entire distributed
+system of event-sourced applications, independently of infrastructure. That means system
 behaviours can be rapidly developed whilst running the entire system synchronously
-in a single thread with a single in-memory database, and then the system can be run
-asynchronously on a cluster with durable databases, with the system performing exactly
+in a single thread with a single in-memory database. And then, the system can be run
+asynchronously on a cluster with durable databases, with the system effecting exactly
 the same behaviour.
 
 
@@ -53,11 +67,22 @@ can be reproduced in code for each project, the persistence mechanism
 for event sourced domain driven design appears as a conceptually cohesive
 mechanism, and so can be "partitioned into a separate lightweight framework".
 
+Whilst some advocate that event sourcing is such a simple thing that you
+can easily roll-your-own event sourcing framework for each project, in practice
+it turns out reaching understanding and satisfaction (reliability, scalability,
+maintainability) is a considerably more complicated and costly undertaking than
+is disclosed by the simple story that is often told.
+
+This library documents the experience of event sourcing across a broad range
+of projects. It also functions as an informative "jumping off" point for those
+who want to create their own framework and "own" all their own code. And it is
+also used by many as a stable and convenient library that can be used to rapidly
+develop working software that will be used in production.
+
 
 Register issues
 ===============
 
 This project is `hosted on GitHub <https://github.com/johnbywater/eventsourcing>`__.
 Please `register any issues, questions, and requests
 <https://github.com/johnbywater/eventsourcing/issues>`__ you may have.
-

docs/topics/quick_start.rst

@@ -12,7 +12,9 @@ general story, which is elaborated over the following pages.
 Install library
 ===============
 
-Please use pip to install the library with the 'sqlalchemy' option.
+It is recommended always to install into a virtual environment.
+
+You can use pip to install the library with the 'sqlalchemy' option (other package installers are available).
 
 ::
 

docs/topics/release_notes.rst

@@ -4,7 +4,7 @@ Release notes
 
 It is the aim of the project that releases with the same major version
 number are backwards compatible, within the scope of the documented
-examples. New major versions indicate a backward incompatible changes
+examples. New major versions indicate backwards incompatible changes
 have been introduced since the previous major version. New minor
 version indicate new functionality has been added, or existing functionality
 extended. New point version indicates existing code or documentation
@@ -22,6 +22,12 @@ systems of application, previously in the "application" package, has been
 moved to a new "system" package.
 
 
+Version 8.2.1 (released 11 March 2020)
+--------------------------------------
+
+Improved documentation.
+
+
 Version 8.2.0 (released 10 March 2020)
 --------------------------------------
 

docs/topics/support.rst

@@ -2,26 +2,31 @@
 Support options
 ===============
 
-Although the library is free to use, it can take some time and
-effort to understand the library and to acquire sufficient
-skill to make a working and well-designed event-sourced system.
-Training workshops and development services are available to
-support professional users of the library in accomplishing their
-goals. Community support is also available.
-
+It has taken a lot of time and effort to create this library.
+Similarly, it will take some time and effort to understand and
+acquire the skills to create a well-designed event-sourced system.
 
-Community support
-=================
+Training workshops and development services are available to
+support your professional use of this library. Community support
+is also available.
 
-The library has a growing community that may be able to help.
+Please also consider supporting the ongoing development and maintenance
+of this library by making a regular donation.
 
-- You can ask questions on the Slack_ channel.
+Professional support
+====================
 
+Design and development services are available to help managers and developers
+with the design and development of their event-sourced applications and systems.
 
-- You can also register issues and requests on our
-  `issue tracker <https://github.com/johnbywater/eventsourcing/issues>`__.
+- Overall assessment of your existing implementation, with recommendations for improvement.
+- Address your specific concerns with how your event-sourced system is built (and running).
+- Coaching developers in the use of the library.
+- Development of sample applications and systems for guidance or demonstration purposes.
+- Development of working applications and systems for production use.
 
-.. _Slack: https://join.slack.com/t/eventsourcinginpython/shared_invite/enQtMjczNTc2MzcxNDI0LTJjMmJjYTc3ODQ3M2YwOTMwMDJlODJkMjk3ZmE1MGYyZDM4MjIxODZmYmVkZmJkODRhZDg5N2MwZjk1YzU3NmY>`__.
+Please contact John Bywater via the Slack_ channel for more information about professional
+support.
 
 
 Training workshops
@@ -37,17 +42,21 @@ Please contact John Bywater via the Slack_ channel for more information about
 training workshops.
 
 
-Professional support
-====================
+Community support
+=================
 
-Design and development services are available to help managers and developers
-with the design and development of their event-sourced applications and systems.
+The library has a growing community that may be able to help.
 
-- Overall assessment of your existing implementation, with recommendations for improvement.
-- Address your specific concerns with how your event-sourced system is built (and running).
-- Coaching developers in the use of the library.
-- Development of sample applications and systems for guidance or demonstration purposes.
-- Development of working applications and systems for production use.
+- You can ask questions on the Slack_ channel.
 
-Please contact John Bywater via the Slack_ channel for more information about professional
-support.
+- You can also register issues and requests on our
+  `issue tracker <https://github.com/johnbywater/eventsourcing/issues>`__.
+
+.. _Slack: https://join.slack.com/t/eventsourcinginpython/shared_invite/enQtMjczNTc2MzcxNDI0LTJjMmJjYTc3ODQ3M2YwOTMwMDJlODJkMjk3ZmE1MGYyZDM4MjIxODZmYmVkZmJkODRhZDg5N2MwZjk1YzU3NmY>`__.
+
+
+Support the project
+===================
+
+Please follow the `Sponsor button <https://github.com/johnbywater/eventsourcing/issues>`__
+on the GitHub project for options.

eventsourcing/__init__.py

@@ -1 +1 @@
-__version__ = "8.2.0"
+__version__ = "8.2.1"