Remove jargon from and simplify README (#950)

Remove a lot of the "operator" and K8s jargon from the top of our
README.

Also simplify and update some of the terminology, consistent
with our updated Juju Terminology doc.

The first part of the doc is copied to ops/__init__.py for consistency.
That appears at the top of our API reference at https://ops.readthedocs.io/

Move the note about dependencies to HACKING.md where I think it belongs.

* Other tweaks per @jnsgruk's review

* Replace "Operator Framework" with "ops library" or just "ops"

Also replace "operator" with "admin" in a few places where it means the
human operator, as "operator" is ambiguous.

Also have separate TOC entries for each module in docs

* Operator Framework -> ops in CI YAML too

.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()