Add info about read_only

docs/developers/store_permissions.md

@@ -10,7 +10,28 @@ Zarr Python has two data models (`Array` and `Group`) and one storage model (`St
 
 ## Store properties related to permissions
 
-### `supports_writes`
+### Instance properties
+
+####  `read_only`
+
+The `read_only` property indicates whether store *instances* should allow `set`, `delete` operations and their permutations. If `read_only` is `True`, then the store should reject any write or delete operations. If `read_only` is `False`, then the store should allow write and delete operations. The property is tested by `Store` methods by calling `self._check_writable()`, which raises a `ValueError` if the store's `read_only` property is true.
+
+The `read_only` property is one of the most likely places to encounter a bug for a few reasons:
+
+- `Store` implementations must remember to call `super.__init__(read_only=read_only)` in their `__init__` method to set the `read_only` property correctly.
+- `Store` implementations must remember to call `self._check_writable()` in their `set` and `delete` methods to enforce the `read_only` property.
+- `Array` and `Group` classes must remember to check alignment with the `read_only` property of the store with any `overwrite` arguments.
+- Top level API functions must remember to check the `read_only` property of the store when creating new arrays or groups. This is complicated by the API functions using "mode" semantics like "w", "r", "a", etc., which are not directly related to the `read_only` property. Each function typically has its own logic for matching mode semntics to the `read_only` property of the store.
+
+This is one of the most likely place to encounter a bug where a `read_only` property is not respected because implementations must remember to call `self._check_writable()` when implementing `store.set()`, which is not implemented in the `Store` abstract base class.
+
+The Zarr spec does not seem to define how APIs should constrain write/delete permissions at the instance level.
+
+### Class properties
+
+The Zarr spec provides distinctions between readable, writeable, and listable stores, but does not define how to distinguish between these groups of store operations. The Zarr Python library has adopted the following properties to distinguish between these groups of operations at the *class* level, which are used by the `Store` abstract base class and the testing framework.
+
+#### `supports_writes`
 
 This is a property of the *class* that should indicate whether the store implements the following methods:
 
@@ -19,7 +40,7 @@ This is a property of the *class* that should indicate whether the store impleme
 
 `supports_writes` is primarily used by tests to determine the expected result of write operations. It is not used by the library to enforce permissions.
 
-### `supports_partial_writes`
+#### `supports_partial_writes`
 
 The purpose of this property of the *class* is currently ambiguous.
 
@@ -31,7 +52,7 @@ But the `FsspecStore` class does not implement this method, but it does have `su
 
 Another interpretation is that it indicates whether the store supports a `byte_range` argument in the `set` method.
 
-### `supports_deletes`
+#### `supports_deletes`
 
 This is a property of the *class* that should indicate whether the store implements the following methods:
 
@@ -46,7 +67,7 @@ The `supports_deletes` property is also used by the testing framework to determi
 !!! note
     Store implementations are agnostic to the Zarr data model. They will delete everything under the given prefix, regardless of whether it is an array, group, or unrelated to the Zarr store.
 
-### `supports_listing`
+#### `supports_listing`
 
 This is a property of the *class* that should indicate whether the store implements the following method: