From 39c7c12fb39f66cf227ee3ba93b31b7162d7bf27 Mon Sep 17 00:00:00 2001 From: DualFroz Date: Wed, 5 Aug 2026 20:40:32 +0200 Subject: [PATCH] chore: drop the core to 0.1.0 and restate the stability promise The API has one set of consumers and no outside users, so declaring 1.0.0 with a stability guarantee was premature. Until 1.0.0 any minor bump may reshape the API; the written guarantee starts there. Plugins pin 0.1.0. --- README.md | 23 +++++++++++++++++------ examples/nemoRepoLastCommit.py | 2 +- nemoRepoCore/__init__.py | 16 +++++++++------- nemoRepoCore/version.py | 2 +- pyproject.toml | 2 +- 5 files changed, 29 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index c83326d..87a27a0 100644 --- a/README.md +++ b/README.md @@ -157,12 +157,13 @@ _ensureCoreOnPath() ```python from nemoRepoCore import requireCore -requireCore("1.0.0") +requireCore("0.1.0") ``` -If the installed core is too old, or a major version apart, this raises and -Nemo skips the extension with a clear message in the log instead of loading a -half working one. +If the installed core is too old, or from a different incompatible series, +this raises and Nemo skips the extension with a clear message in the log +instead of loading a half working one. See "Versioning" for what counts as a +different series while the core is still `0.x`. ### 3. Register your defaults @@ -295,14 +296,24 @@ When `error` is set, treat every other field as unknown. Semantic versioning, enforced at load time by `requireCore`. +The core is at `0.1.0`, which in semver means the API is not settled yet: its +only consumers are the five plugins listed above and it has no outside users. +Until `1.0.0`, any minor bump may remove or rename anything in the API table. +`requireCore` follows the same rule and treats the minor as the breaking +component while the major is `0`, so a plugin that asked for `0.1.0` refuses to +load against `0.2.0` instead of breaking somewhere deeper. + +From `1.0.0` on, the guarantee below is the written one and holds: + - Within a major version nothing in the API table is removed or renamed, and signatures only ever gain optional arguments. A plugin that asked for `1.0.0` keeps working on `1.4.0`. - A major bump may change anything. `requireCore` refuses to run a plugin against a different major version, so the failure is loud and immediate rather than subtle. -- Anything not in the API table, and anything with a leading underscore, is - internal. + +Anything not in the API table, and anything with a leading underscore, is +internal either way. ## Tested on diff --git a/examples/nemoRepoLastCommit.py b/examples/nemoRepoLastCommit.py index 634481b..fc974bc 100644 --- a/examples/nemoRepoLastCommit.py +++ b/examples/nemoRepoLastCommit.py @@ -38,7 +38,7 @@ from gi.repository import GObject, Nemo from nemoRepoCore import (findRepoRoot, localDirectoryPath, repoCache, requireCore) -requireCore("1.0.0") +requireCore("0.1.0") class LastCommitColumnProvider(GObject.GObject, Nemo.ColumnProvider, diff --git a/nemoRepoCore/__init__.py b/nemoRepoCore/__init__.py index 66cce49..4e118f5 100644 --- a/nemoRepoCore/__init__.py +++ b/nemoRepoCore/__init__.py @@ -10,7 +10,7 @@ Minimal plugin: from nemoRepoCore import (coreConfig, findRepoRoot, localDirectoryPath, repoCache, requireCore) - requireCore("1.0.0") + requireCore("0.1.0") coreConfig.registerDefaults({"indicators": {"mine": {"enabled": True}}}) @@ -28,12 +28,14 @@ Minimal plugin: Stability policy for everything listed in __all__: - * Within a major version, names are never removed and signatures only ever - gain optional arguments. New helpers may appear; a plugin that asked for - 1.0.0 keeps working on 1.4.0. - * A major bump may remove or reshape anything. requireCore() refuses to - load a plugin against a different major, so a mismatch is a clear error - at startup instead of a subtle misbehaviour later. + * The core is 0.x, so the API is not settled yet: any 0.x minor bump may + remove or reshape anything. requireCore() knows this and treats the minor + as the breaking component while the major is 0, so a plugin that asked + for 0.1.0 refuses to load against 0.2.0 instead of misbehaving later. + * From 1.0.0 on the usual guarantee applies: within a major version names + are never removed and signatures only ever gain optional arguments, so a + plugin that asked for 1.0.0 keeps working on 1.4.0, and only a major bump + may reshape anything. * Names not in __all__, and anything with a leading underscore, are internal and may change in any release. """ diff --git a/nemoRepoCore/version.py b/nemoRepoCore/version.py index 935a6b4..50b68e2 100644 --- a/nemoRepoCore/version.py +++ b/nemoRepoCore/version.py @@ -1,6 +1,6 @@ """Version of the core library and the compatibility check plugins call.""" -coreVersion = "1.0.0" +coreVersion = "0.1.0" class CoreVersionError(RuntimeError): diff --git a/pyproject.toml b/pyproject.toml index e023b70..ff18398 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "nemo-repo-core" -version = "1.0.0" +version = "0.1.0" description = "Shared foundation for repository-aware Nemo file manager plugins" readme = "README.md" requires-python = ">=3.8"