Remove jargon from and simplify README

.github/workflows/db-charm-tests.yaml

@@ -1,4 +1,4 @@
-name: Data Platform Charm Tests
+name: Data Charm Tests
 
 on: [push, pull_request, workflow_call]
 

.github/workflows/framework-tests.yaml

@@ -1,4 +1,4 @@
-name: Operator Framework Tests
+name: ops Tests
 
 on: [push, pull_request, workflow_call]
 

HACKING.md

@@ -86,14 +86,14 @@ should always be accompanied by user-focused documentation that is posted to
 https://juju.is/docs/sdk.  The content for this site is written and hosted on
 https://discourse.charmhub.io/c/doc.  New documentation should get a new
 topic/post on this discourse forum and then should be linked into the main
-docs navigation page(s) as appropriate.  The operator framework SDK page
+docs navigation page(s) as appropriate.  The ops library's SDK page
 content is pulled from
 [here](https://discourse.charmhub.io/t/the-charmed-operator-software-development-kit-sdk-docs/4449).
 Each page on [juju.is](https://juju.is/docs/sdk) has a link at the bottom that
 takes you to the corresponding discourse page where docs can be commented on
 and edited (if you have earned those privileges).
 
-The Operator Framework API docs are automatically built and published to
+The ops library's API reference is automatically built and published to
 [here](https://ops.readthedocs.io/en/latest/).  Please be complete with
 docstrings and keep them informative for _users_.
 
@@ -105,9 +105,17 @@ Currently we don't publish separate versions of documentation for separate relea
 
 next to the relevant content (e.g. headings, etc.).
 
+
+## Dependencies
+
+The Python dependencies of `ops` are kept as minimal as possible, to avoid
+bloat and to minimise conflict with the charm's dependencies. The dependencies
+are listed in [requirements.txt](requirements.txt).
+
+
 # Publishing a Release
 
-To make a release of the Operator Framework, do the following:
+To make a release of the ops library, do the following:
 
 1. Visit the [releases page on github](https://github.com/canonical/operator/releases).
 2. Click "Draft a new release"
@@ -118,7 +126,7 @@ To make a release of the Operator Framework, do the following:
 
 This will trigger an automatic build for the Python package and publish it to PyPI (the API token/secret is already set up in the repository settings).
 
-See [.github/workflows/publish.yml](.github/workflows/publish.yml) for details. (Note that the versions in publish.yml refer to versions of the github actions, not the versions of the Operator Framework.)
+See [.github/workflows/publish.yml](.github/workflows/publish.yml) for details. (Note that the versions in publish.yml refer to versions of the github actions, not the versions of the ops library.)
 
 You can troubleshoot errors on the [Actions Tab](https://github.com/canonical/operator/actions).
 

README.md

@@ -1,103 +1,59 @@
-# The Charmed Operator Framework
+# The ops library
 
-This Charmed Operator Framework simplifies [operator](https://charmhub.io/about) development
-for [model-driven application management](https://juju.is/model-driven-operations).
+<!-- The text below is also at the top of ops/__init__.py. Keep in sync! -->
 
-Operators emerged from the Kubernetes community; an operator is software that drives lifecycle
-management, configuration, integration and daily actions for an application. Operators simplify
-software management and operations. They capture reusable app domain knowledge from experts in a
-software component that can be shared.
+The ops library is a Python framework ([`available on PyPI`](https://pypi.org/project/ops/)) for developing
+and testing [Juju](https://juju.is/) charms in a consistent way, using standard Python constructs
+to allow for clean, maintainable, and reusable code.
 
-This project extends the operator pattern to enable
-[charmed operators](https://juju.is/universal-operators), not just for Kubernetes but also
-operators for traditional Linux application management.
+A charm is an operator -- business logic encapsulated in a reusable software
+package that automates every aspect of an application's life.
 
-Operators use a [Charmed Operator Lifecycle Manager
-(Charmed OLM)](https://juju.is/operator-lifecycle-manager) to coordinate their work in a cluster.
-The system uses Golang for concurrent event processing under the hood, but enables the operators to
-be written in Python.
+Charms written with ops support Kubernetes using Juju's "sidecar charm"
+pattern, as well as charms that deploy to Linux-based machines and containers.
 
-## Simple, composable operators
+Charms should do one thing and do it well. Each charm drives a single
+application and can be integrated with other charms to deliver a complex
+system. A charm handles creating the application in addition to scaling,
+configuration, optimisation, networking, service mesh, observability, and other
+day-2 operations specific to the application.
 
-Operators should 'do one thing and do it well'. Each operator drives a single microservice and can
-be [composed with other operators](https://juju.is/integration) to deliver a complex application.
+The ops library is part of the Charm SDK (the other part being Charmcraft).
+Full developer documentation for the Charm SDK is available at
+https://juju.is/docs/sdk.
 
-It is better to have small, reusable operators that each drive a single microservice very well.
-The operator handles instantiation, scaling, configuration, optimisation, networking, service mesh,
-observability, and day-2 operations specific to that microservice.
+To learn more about Juju, visit https://juju.is/docs/olm.
 
-Operator composition takes place through declarative integration in the OLM. Operators declare
-integration endpoints, and discover lines of integration between those endpoints dynamically at
-runtime.
 
-## Pure Python operators
+## Pure Python
 
-The framework provides a standard Python library and object model that represents the application
-graph, and an event distribution mechanism for distributed system coordination and communication.
+The framework provides a standardised Python object model that represents the
+application graph, as well as an event-handling mechanism for distributed
+system coordination and communication.
 
-The OLM is written in Golang for efficient concurrency in event handling and distribution.
-Operators can be written in any language. We recommend this Python framework for ease of design,
-development and collaboration.
+The latest version of ops requires Python 3.8 or above.
 
-## Better collaboration
+Juju itself is written in Go for efficient concurrency even in large
+deployments. Charms can be written in any language, however, we recommend using
+Python with this framework to make development easier and more standardised.
+All new charms at Canonical are written using it.
 
-Operator developers publish Python libraries that make it easy to integrate your operator with
-their operator. The framework includes standard tools to distribute these integration libraries and
-keep them up to date.
 
-Development collaboration happens at [Charmhub.io](https://charmhub.io/) where operators are
-published along with integration libraries. Design and code review discussions are hosted in the
-Charmhub [discourse]. We recommend the [Open Operator Manifesto](https://charmhub.io/manifesto)
-as a guideline for high quality operator engineering.
+## Getting started
 
-## Event serialization and operator services
+A package of operator code is called a charmed operator or simply "charm".
+You'll use [charmcraft](https://juju.is/docs/sdk/install-charmcraft) to
+register your charm name and publish it when you are ready. You can follow one
+of our [charming tutorials](https://juju.is/docs/sdk/tutorials) to get started
+writing your first charm.
 
-Distributed systems can be hard! So this framework exists to make it much simpler to reason about
-operator behaviour, especially in complex deployments. The Charmed OLM provides
-[operator services](https://juju.is/operator-services) such as provisioning, event delivery,
-leader election and model management.
 
-Coordination between operators is provided by a cluster-wide event distribution system. Events are
-serialized to avoid race conditions in any given container or machine. This greatly simplifies the
-development of operators for high availability, scale-out and integrated applications.
+## Testing your charms
 
-## Model-driven Operator Lifecycle Manager
-
-A key goal of the project is to improve the user experience for admins working with multiple
-different operators.
-
-We embrace [model-driven operations](https://juju.is/model-driven-operations) in the Charmed
-Operator Lifecycle Manager. The model encompasses capacity, storage, networking, the application
-graph and administrative access.
-
-Admins describe the application graph of integrated microservices, and the OLM then drives
-instantiation. A change in the model is propagated to all affected operators, reducing the
-duplication of effort and repetition normally found in operating a complex topology of services.
-
-Administrative actions, updates, configuration and integration are all driven through the OLM.
-
-# Getting started
-
-A package of operator code is called a charmed operator or “charm. You will use `charmcraft` to
-register your operator name, and publish it when you are ready. There are more details on how to
-get a complete development environment setup over in the
-[documentation](https://juju.is/docs/sdk/dev-setup)
-
-Charmed Operators written using the Charmed Operator Framework are just Python code. The goal
-is to feel natural for somebody used to coding in Python, and reasonably easy to learn for somebody
-who is not a pythonista.
-
-The dependencies of the operator framework are kept as minimal as possible; currently that's Python
-3.8 or greater, and the small number of Python libraries referenced in [requirements.txt](requirements.txt).
-
-For a brief intro on how to get started, check out the
-[Hello, World!](https://juju.is/docs/sdk/hello-world) section of the documentation!
-
-# Testing your charmed operators
-
-The operator framework provides a testing harness, so you can check your charmed operator does the
-right thing in different scenarios, without having to create a full deployment.
-`pydoc3 ops.testing` has the details, including this example:
+The framework provides a testing harness, so you can ensure that your charm
+does the right thing in different scenarios, without having to create
+a full deployment. Our [API documentation](https://ops.readthedocs.io/en/latest/#module-ops.testing)
+has the details, including this example:
 
 ```python
 harness = Harness(MyCharm)
@@ -111,21 +67,22 @@ harness.update_relation_data(relation_id, 'postgresql/0', {'key': 'val'})
 self.assertEqual(harness.charm. ...)
 ```
 
+
 ## Talk to us
 
 If you need help, have ideas, or would just like to chat with us, reach out on
 the Charmhub [Mattermost].
 
-We also pay attention to the Charmhub [Discourse]
+We also pay attention to the Charmhub [Discourse].
 
-You can deep dive into the [API docs] if that's your thing.
+And of course you can deep dive into the [API reference].
 
-[discourse]: https://discourse.charmhub.io
-[api docs]: https://ops.rtfd.io/
-[sdk docs]: https://juju.is/docs/sdk
-[mattermost]: https://chat.charmhub.io/charmhub/channels/charm-dev
+[Discourse]: https://discourse.charmhub.io/
+[API reference]: https://ops.readthedocs.io/
+[Mattermost]: https://chat.charmhub.io/charmhub/channels/charm-dev
 
-## Operator Framework development
 
-See [HACKING.md](HACKING.md) for details on dev environments, testing, etc.
+## Development of the framework
 
+See [HACKING.md](HACKING.md) for details on dev environments, testing, and so
+on.

docs/conf.py

@@ -47,7 +47,7 @@ def _compute_navigation_tree(context):
 
 # -- Project information -----------------------------------------------------
 
-project = 'The Operator Framework'
+project = 'The ops library'
 copyright = '2019-2023, Canonical Ltd.'
 author = 'Canonical Ltd'
 

docs/index.rst

@@ -1,31 +1,31 @@
 
-Welcome to The Operator Framework's documentation!
-==================================================
+ops library API reference
+=========================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-ops package
-===========
+ops module
+==========
 
 .. automodule:: ops
 
 
 ops.pebble module
------------------
+=================
 
 .. automodule:: ops.pebble
 
 
 ops.testing module
-------------------
+==================
 
 .. automodule:: ops.testing
 
 
-Indices and tables
-==================
+Indices
+=======
 
 * :ref:`genindex`
 * :ref:`modindex`

ops/__init__.py

@@ -12,31 +12,33 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""The Charmed Operator Framework.
+# NOTE: The text below is also at the top of README.md. Keep in sync!
 
-The Charmed Operator Framework allows the development of operators in a simple
-and straightforward way, using standard Python structures to allow for clean,
-maintainable, and reusable code.
+"""The ops library: a Python framework for writing Juju charms.
 
-A Kubernetes operator is a container that drives lifecycle management,
-configuration, integration and daily actions for an application. Operators
-simplify software management and operations. They capture reusable app domain
-knowledge from experts in a software component that can be shared.
+The ops library is a Python framework (`available on PyPI`_) for developing
+and testing Juju charms in a consistent way, using standard Python constructs
+to allow for clean, maintainable, and reusable code.
 
-The Charmed Operator Framework extends the "operator pattern" to enable Charmed
-Operators, packaged as and often referred to as "charms". Charms are not just
-for Kubernetes but also operators for traditional Linux application management.
-Operators use an Operator Lifecycle Manager (OLM), like Juju, to coordinate
-their work in a cluster. The system uses Golang for concurrent event processing
-under the hood, but enables the operators to be written in Python.
+A charm is an operator -- business logic encapsulated in a reusable software
+package that automates every aspect of an application's life.
 
-Operators should do one thing and do it well. Each operator drives a single
-application or service and can be composed with other operators to deliver a
-complex application or service. An operator handles instantiation, scaling,
-configuration, optimisation, networking, service mesh, observability,
-and day-2 operations specific to that application.
+Charms written with ops support Kubernetes using Juju's "sidecar charm"
+pattern, as well as charms that deploy to Linux-based machines and containers.
 
-Full developer documentation is available at https://juju.is/docs/sdk.
+Charms should do one thing and do it well. Each charm drives a single
+application and can be integrated with other charms to deliver a complex
+system. A charm handles creating the application in addition to scaling,
+configuration, optimisation, networking, service mesh, observability, and other
+day-2 operations specific to the application.
+
+The ops library is part of the Charm SDK (the other part being Charmcraft).
+Full developer documentation for the Charm SDK is available at
+https://juju.is/docs/sdk.
+
+To learn more about Juju, visit https://juju.is/docs/olm.
+
+.. _available on PyPI: https://pypi.org/project/ops/
 """
 
 # The "from .X import Y" imports below don't explicitly tell Pyright (or MyPy)

ops/charm.py

@@ -117,7 +117,7 @@ def defer(self):
         raise RuntimeError('cannot defer action events')
 
     def restore(self, snapshot: Dict[str, Any]):
-        """Used by the operator framework to record the action.
+        """Used by the framework to record the action.
 
         Not meant to be called directly by charm code.
         """

ops/framework.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""The Operator Framework infrastructure."""
+"""The ops library's infrastructure."""
 
 import collections
 import collections.abc
@@ -541,7 +541,7 @@ def __str__(self):
 
 
 class Framework(Object):
-    """Main interface from the Charm to the Operator Framework internals."""
+    """Main interface from the Charm to the ops library's infrastructure."""
 
     on = FrameworkEvents()  # type: ignore
 

ops/log.py

@@ -35,7 +35,7 @@ def __init__(self, model_backend: "_ModelBackend", level: int = logging.DEBUG):
     def emit(self, record: logging.LogRecord):
         """Send the specified logging record to the Juju backend.
 
-        This method is not used directly by the Operator Framework code, but by
+        This method is not used directly by the ops library, but by
         :class:`logging.Handler` itself as part of the logging machinery.
         """
         self.model_backend.juju_log(record.levelname, self.format(record))

ops/main.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Main entry point to the Operator Framework.
+"""Main entry point to the framework.
 
 Note that this module is callable, and calls the :func:`ops.main.main` function.
 This is so that :code:`import ops` followed by :code:`ops.main(MyCharm)` works
@@ -379,7 +379,7 @@ def main(charm_class: Type[ops.charm.CharmBase],
     model_backend = ops.model._ModelBackend()
     debug = ('JUJU_DEBUG' in os.environ)
     setup_root_logging(model_backend, debug=debug)
-    logger.debug("Operator Framework %s up and running.", ops.__version__)  # type:ignore
+    logger.debug("ops %s up and running.", ops.__version__)  # type:ignore
 
     dispatcher = _Dispatcher(charm_dir)
     dispatcher.run_any_legacy_hook()