Add versioning page to docs (and minor stpipe submodule cleanup) (#2322)

Author: braingram

changes/2322.docs.rst

@@ -0,0 +1 @@
+Add versioning page to docs describing public vs private API and romancal versioning scheme.

docs/roman/package_index.rst

@@ -1,6 +1,7 @@
 .. toctree::
    :maxdepth: 2
 
+   versioning.rst
    assign_wcs/index.rst
    associations/index.rst
    dark_current/index.rst

docs/roman/versioning.rst

@@ -0,0 +1,36 @@
+.. _romancal-version-scheme:
+
+Versioning Scheme
+-----------------
+
+.. note::
+
+   This section addresses the release version to PyPI.
+   It is not to be confused with the DMS quarterly build version,
+   which has a different numbering scheme (see
+   `software vs. DMS builds <https://github.com/spacetelescope/romancal/blob/main/README.md#software-vs-dms-build-version-map>`_).
+
+The ``romancal`` package follows `semantic versioning <https://semver.org/>`_ with a few minor
+exceptions noted below. In brief this means that backwards incompatible changes are allowed
+in major version changes, minor versions can contain new features and patch versions
+can contain only bug fixes.
+
+.. _romancal-public-vs-private-api:
+
+API: Public vs Private
+----------------------
+
+As per Python convention, any API name that starts with underscore
+(e.g., ``_my_private_function``) is considered private.
+Any API not officially documented (i.e., you only found it after some extensive
+code-diving) is also considered private.
+
+Additionally test code is considered private. This includes:
+
+* all ``conftest.py`` files
+* modules that start with ``test_*`` or are named ``tests``
+* everything under ``romancal.regtest``
+
+If there is code that you would like to be public, please search
+the open `issues <https://github.com/spacetelescope/romancal/issues>`_ and
+open a new one describing what you would like to be made public.

romancal/lib/suffix.py

@@ -176,7 +176,7 @@ def _find_suffixes():
     is worth doing dynamically or only as a utility to update
     a static list.
     """
-    from romancal.stpipe.utilities import all_steps
+    from romancal.stpipe._utilities import all_steps
 
     # First traverse the code base and find all
     # `Step` classes. The default suffix is the