Document rules for declaring the "public" datalad-next API

Closes #613

CONTRIBUTING.md

@@ -52,9 +52,7 @@ There is no limit to the number of files. Contributors should strive for files w
 
 Within a sub-package, code should generally use relative imports. The corresponding tests should also import the tested code via relative imports.
 
-Code users should be able to import the most relevant functionality from the sub-package's `__init__.py`.
-
-If possible, sub-packages should have a "central" place for imports of functionality from outside `datalad-next` and the Python standard library. Other sub-package code should then import from this place via relative imports. This aims to make external dependencies more obvious, and import-error handling and mitigation for missing dependencies simpler and cleaner. Such a location could be the sub-package's `__init__.py`, or possibly a dedicated `dependencies.py`.
+Code users should be able to import the most relevant functionality from the sub-package's `__init__.py`. Only items importable from the sub-package's top-level are considered to be part of its "public" API.
 
 Sub-packages should be as self-contained as possible. Individual components in `datalad-next` should strive to be easily migratable to the DataLad core package. This means that any organization principles like *all-exceptions-go-into-a-single-location-in-datalad-next* do not apply. For example, each sub-package should define its exceptions separately from others. When functionality is shared between sub-packages, absolute imports should be made.
 

README.md

@@ -142,6 +142,33 @@ this extension causes a range of patches to be applied to the `datalad` package
 to enable them. A comprehensive description of the current set of patch is
 available at http://docs.datalad.org/projects/next/en/latest/#datalad-patches
 
+## Developing with DataLad NEXT
+
+This extension package moves fast in comparison to the core package. Nevertheless,
+attention is paid to API stability, adequate semantic versioning, and informative
+changelogs.
+
+### Public vs internal API
+
+Anything that can be imported directly from any of the sub-packages in
+`datalad_next` is considered to be part of the public API. Changes to this API
+determine the versioning, and development is done with the aim to keep this API
+as stable as possible. This includes signatures and return value behavior.
+
+As an example: `from datalad_next.runners import iter_git_subproc` imports a
+part of the public API, but `from datalad_next.runners.git import
+iter_git_subproc` does not.
+
+### Use of the internal API
+
+Developers can obviously use parts of the non-public API. However, this should
+only be done with the understanding that these components may change from one
+release to another, with no guarantee of transition periods, deprecation
+warnings, etc.
+
+Developers are advised to never reuse any components with names starting with
+`_` (underscore). Their use should be limited to their individual subpackage.
+
 ## Acknowledgements
 
 This DataLad extension was developed with funding from the Deutsche

changelog.d/20240205_165507_michael.hanke_bf_613.md

@@ -0,0 +1,18 @@
+### 💫 Enhancements and new features
+
+- Code organization is adjusted to clearly indicate what is part of the
+  package's public Python API. Anything that can be imported directly from
+  the top-level of any sub-package is part of the public API.
+  As an example: `from datalad_next.runners import iter_git_subproc`
+  imports a   part of the public API, but
+  `from datalad_next.runners.git import iter_git_subproc` does not.
+  See `README.md` for more information.
+  Fixes https://github.com/datalad/datalad-next/issues/613 via
+  https://github.com/datalad/datalad-next/pull/615 (by @mih)
+  https://github.com/datalad/datalad-next/pull/617 (by @mih)
+  https://github.com/datalad/datalad-next/pull/618 (by @mih)
+  https://github.com/datalad/datalad-next/pull/619 (by @mih)
+  https://github.com/datalad/datalad-next/pull/620 (by @mih)
+  https://github.com/datalad/datalad-next/pull/621 (by @mih)
+  https://github.com/datalad/datalad-next/pull/622 (by @mih)
+  https://github.com/datalad/datalad-next/pull/623 (by @mih)