napkinstack 0.6.1__tar.gz → 0.6.2__tar.gz

{napkinstack-0.6.1 → napkinstack-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.6.1
+Version: 0.6.2
 Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
 License-Expression: MIT
 License-File: LICENSE

{napkinstack-0.6.1 → napkinstack-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.6.1"
+version = "0.6.2"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

{napkinstack-0.6.1 → napkinstack-0.6.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.6.1"
+version = "0.6.2"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

{napkinstack-0.6.1 → napkinstack-0.6.2}/src/napkinstack/project.py

@@ -23,6 +23,8 @@ from napkinstack import __version__
 SOURCE = "https://github.com/NapkinStack/engineering-os.git"
 ANSWERS = ".copier-answers.yml"
 DOWNGRADE = re.compile(r"You are downgrading from (\S+) to (\S+)\.")
+# The forms of a GitHub source Copier records, from which a release page can be named.
+GITHUB = re.compile(r"^(?:https://github\.com/|git@github\.com:|gh:)(?P<repo>[^/]+/[^/]+?)(?:\.git)?/?$")
 
 
 def default_ref() -> str:
@@ -30,6 +32,23 @@ def default_ref() -> str:
     return f"v{__version__}"
 
 
+def release_notes(source: str, previous: str, current: str) -> str:
+    """Where to read what a version changes, before taking it. The published package carries
+    the engine and not the skeleton, so comparing two releases of it cannot show what an update
+    merges (D63): the notes are the only channel, and the command that brings the change names
+    them (D62).
+
+    It names the whole distance travelled, never the target alone (D66). One `nstack update`
+    can cross several versions, and the change that conflicts with the project's own files may
+    come from any of them: a release page holds one version and cannot answer for the others.
+    The CHANGELOG at the tag holds them all."""
+    found = GITHUB.match(source.strip())
+    if found:
+        return (f"https://github.com/{found['repo']}/blob/{current}/CHANGELOG.md"
+                f" — every section above {previous}")
+    return f"CHANGELOG.md, every section above {previous}, in {source}"
+
+
 def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
     return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
 
@@ -67,6 +86,15 @@ def _explain(exc: Exception, command: str, where: Path, source: str, ref: str) -
     if text.startswith("Cannot update: version from last update not detected"):
         return (f"FAIL [{command}] The project does not come from a published version (_commit in {ANSWERS}): "
                 f"no merge base.\n{action}create the project from a vX.Y.Z tag.")
+    # An OSError carrying an errno is the filesystem answering, not the template being out of
+    # reach: a full disk, a read-only path, a directory an interrupted run left behind. Calling
+    # it "unreachable" sends the reader to --source, --ref and the network, none of which can
+    # help (D65). The OSErrors Copier raises for a template it could not read carry no errno.
+    if isinstance(exc, OSError) and exc.errno:
+        return (f"FAIL [{command}] {command} stopped on a local filesystem error: {text}\n"
+                f"{action}read the error above and fix what it names \u2014 space, permissions, or "
+                "something left behind by an interrupted run. The template and the network are "
+                "not in question.")
     if isinstance(exc, OSError) or text == "Local template must be a directory.":
         lines = [line.split("|", 1)[-1].strip() for line in text.splitlines() if line.strip()]
         # git writes the cause on an `error:` line and the outcome on a `fatal:` one; keeping
@@ -190,5 +218,7 @@ def update(root: Path, ref: str) -> int:
 
     print(f"Branch {branch}: NapkinStack {previous} -> {current}, merged with the project's "
           "adaptations.")
+    print(f"What {previous} -> {current} changes, engine and project apart: "
+          f"{release_notes(str(_answers(root).get('_src_path') or ''), previous, current)}")
     print(f"\nNext step: git push -u origin {branch}, then open the PR; CI validates it.")
     return 0