Tweak the changelog add command (baserow#5246)

Author: picklepete

.agents/skills/create-changelog/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: create-changelog
+description: Generate a changelog entry for the current Git branch by inspecting changed files, classifying the domain and type, writing a short public-friendly message, and running `just changelog add` after the user confirms. Use this skill whenever the user asks to "create a changelog", "add a changelog entry", "changelog this branch", "write changelog", or otherwise signals they want to record what their branch changes — even if they don't mention `just` or the exact command.
+---
+
+# create-changelog
+
+Create a changelog entry for the work on the current Git branch. The entry is registered by running:
+
+```
+just changelog add --domain {domain} --type {type} --message '{message}'
+```
+
+## Workflow
+
+Follow these steps in order. Do not skip ahead — the user confirms before anything is committed.
+
+### 1. Gather the diff
+
+Run these commands from the repository root to understand what has changed on this branch relative to `develop`:
+
+```bash
+git rev-parse --abbrev-ref HEAD
+git diff --name-status develop...HEAD
+git diff --stat develop...HEAD
+git log develop..HEAD --oneline
+```
+
+`develop...HEAD` (three dots) gives the changes introduced on this branch since it diverged from `develop`, which is what a changelog entry should describe.
+
+If any of the following is true, stop and tell the user there's nothing to changelog:
+
+- `git diff --name-status develop...HEAD` is empty.
+- The current branch is `develop` itself, or is `main`/`master`.
+- `develop` does not exist as a ref (in which case mention it and ask how they'd like to proceed).
+
+If the diff is large enough that the file list alone isn't informative, also peek at `git diff develop...HEAD -- <path>` for a few of the most-changed files to get a sense of the substance of the change. Prefer looking at a handful of representative files over dumping the entire diff.
+
+### 2. Pick the domain
+
+The domain must be exactly one of: `core`, `database`, `dashboard`, `builder`, `automation`, `integration`. These correspond to modules in the codebase.
+
+Choose the domain with the most changed files. Use directory names and file paths as the primary signal — e.g. files under a `dashboard/` directory belong to `dashboard`. If paths are ambiguous, fall back to the substance of the changes (e.g. migration files → `database`, webhook/third-party API code → `integration`).
+
+If there's a close tie, prefer the domain that contains the change with the most lines modified, or the one the branch name and commit messages most clearly point at. Don't overthink it — pick the single best match.
+
+### 3. Pick the type
+
+The type must be exactly one of: `bug`, `feature`, `refactor`, `breaking_change`.
+
+Rough guide:
+
+- `bug` — fixes incorrect behavior. Signals: commit messages with "fix", "bug", "regression"; small targeted changes; tests added alongside a fix.
+- `feature` — adds capability that wasn't there before. Signals: new files, new endpoints, new UI, new configuration options.
+- `refactor` — reshapes existing code without changing behavior. Signals: moves/renames, no new functionality, no bug being fixed, tests largely unchanged.
+- `breaking_change` — changes that require consumers to update. Signals: removed/renamed public APIs, changed function signatures, database migrations that drop columns, config format changes.
+
+A breaking change beats the other labels when it applies — if a refactor removes a public function, it's a `breaking_change`. Otherwise, pick the single best fit and move on.
+
+### 4. Write the message
+
+The message describes what changed, in plain English, for a mixed audience of developers and non-technical users reading a public changelog.
+
+Rules:
+
+- **Max 100 characters**, including spaces. Count them.
+- Plain English, no jargon, no internal code names, no file paths, no class names.
+- Present tense, sentence case, no trailing period. Start with a verb when natural.
+- Describe the user-visible effect, not the implementation. "Speeds up dashboard loading" beats "Adds index to dashboard_widgets.user_id".
+- Don't start with the type or domain (e.g. don't write "Fix: ..." — the type and domain are separate fields).
+- Single line, no newlines.
+
+**Examples:**
+
+Good:
+- `Dashboards now load faster when you have many widgets`
+- `Fixes an error that could lose changes when saving automations`
+- `Adds a bulk import option for contacts`
+
+Too technical:
+- `Refactor DashboardWidget.render() to use memoization`
+- `Patch NPE in AutomationSaver.persist()`
+
+Too vague:
+- `Various improvements`
+- `Bug fixes`
+
+### 5. Show the proposal and get confirmation
+
+Present the chosen values to the user in this exact shape so they're easy to scan:
+
+```
+Domain:  <domain>
+Type:    <type>
+Message: <message>
+```
+
+Follow with a one- or two-sentence rationale explaining *why* you picked that domain and type (e.g. "7 of 9 changed files are under `builder/`, and the branch adds a new step type, so I called it a new feature.") and then the full command that will be run:
+
+```
+just changelog add --domain <domain> --type <type> --message '<message>'
+```
+
+Ask the user to confirm, or to tell you what to change. If they ask for changes, redo whichever steps are affected and present an updated proposal — don't run the command until the user explicitly confirms.
+
+### 6. Execute
+
+Once the user confirms, run the command:
+
+```bash
+just changelog add --domain <domain> --type <type> --message '<message>'
+```
+
+Wrap the message in single quotes so apostrophes, spaces, and punctuation pass through correctly. If the message itself contains a single quote, close-escape-open it (`'\''`) or rewrite the message to avoid it — preferably the latter, since changelog messages rarely need apostrophes.
+
+The issue number is automatically extracted from the branch name (e.g. a branch named `1234-fix-something` yields issue `1234`). If no issue number is found in the branch name, the entry is created without one.
+
+Show the command's output to the user and confirm it succeeded. If `just` errors (for example, the arguments aren't accepted), surface the error and offer to adjust and retry.
+
+## Notes
+
+- If the user runs this skill multiple times in one session with different intents, re-run the diff — don't reuse cached results, because the branch state may have changed.

changelog/src/changelog.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+
 import os
 import shutil
 from pathlib import Path
@@ -17,38 +18,69 @@
 # Parent directory
 default_path = str(Path(os.path.dirname(__file__)).parent)
 
+DOMAIN_TYPES = list(domain_types.keys())
+ENTRY_TYPES = list(changelog_entry_types.keys())
+
 
 @app.command()
-def add(working_dir: Optional[str] = typer.Option(default=default_path)):
-    domain_type = typer.prompt(
+def add(
+    working_dir: Optional[str] = typer.Option(default=default_path),
+    domain: Optional[str] = typer.Option(None, "--domain", help=f"The module domain this changelog pertains to. One of: {', '.join(DOMAIN_TYPES)}."),
+    entry_type: Optional[str] = typer.Option(
+        None, "--type", help=f"The entry type this changelog is. One of: {', '.join(ENTRY_TYPES)}.",
+    ),
+    message: Optional[str] = typer.Option(
+        None, "--message", help="The changelog message. Describe in non-technical language what the bug, feature or refactor accomplishes."
+    ),
+    issue: Optional[str] = typer.Option(None, "--issue", help="The GitHub issue ID. Defaults to finding it through the branch name prefix."),
+):
+    domain_type = domain or typer.prompt(
         "Domain",
-        type=Choice(list(domain_types.keys())),
+        type=Choice(DOMAIN_TYPES),
         default=DatabaseDomain.type,
     )
-    changelog_type = typer.prompt(
+    if domain_type not in DOMAIN_TYPES:
+        raise typer.BadParameter(
+            f"must be one of: {', '.join(DOMAIN_TYPES)}", param_hint="--domain"
+        )
+
+    changelog_type = entry_type or typer.prompt(
         "Type of changelog",
-        type=Choice(list(changelog_entry_types.keys())),
+        type=Choice(ENTRY_TYPES),
         default=BugChangelogEntry.type,
     )
-    issue_number = typer.prompt(
-        "Issue number", type=str, default=ChangelogHandler.get_issue_number() or ""
-    )
-
-    message = typer.prompt("Message", default="")
-
-    if issue_number.isdigit():
+    if changelog_type not in ENTRY_TYPES:
+        raise typer.BadParameter(
+            f"must be one of: {', '.join(ENTRY_TYPES)}",
+            param_hint="--type",
+        )
+    if issue is not None:
+        issue_number = issue
+    elif domain is not None and entry_type is not None and message is not None:
+        issue_number = ChangelogHandler.get_issue_number() or ""
+    else:
+        issue_number = typer.prompt(
+            "Issue number", type=str, default=ChangelogHandler.get_issue_number() or ""
+        )
+    final_message = message or typer.prompt("Message", default="")
+
+    if issue_number and not str(issue_number).isdigit():
+        raise typer.BadParameter("must be a numeric GitHub issue ID", param_hint="--issue")
+
+    if str(issue_number).isdigit():
         issue_number = int(issue_number)
 
     if issue_number == "":
         issue_number = None
 
-    ChangelogHandler(working_dir).add_entry(
+    path = ChangelogHandler(working_dir).add_entry(
         domain_type,
         changelog_type,
-        message,
+        final_message,
         issue_number=issue_number,
         issue_origin="github",  # All new changelogs originate from GitHub
     )
+    typer.echo(path)
 
 
 @app.command()

changelog/src/changelog_entry.py

@@ -1,7 +1,7 @@
 import abc
 import os
 from datetime import datetime, timezone
-from typing import Dict, List, Optional, Union
+from typing import Dict, List, Optional, Union, Any
 
 GITLAB_URL = os.environ.get("GITLAB_URL", "https://gitlab.com/baserow/baserow")
 GITHUB_URL = os.environ.get("GITHUB_URL", "https://github.com/baserow/baserow")
@@ -21,7 +21,7 @@ def generate_entry_dict(
         issue_origin: str,
         issue_number: Optional[int] = None,
         bullet_points: List[str] = None,
-    ) -> Dict[str, any]:
+    ) -> Dict[str, Any]:
         if bullet_points is None:
             bullet_points = []
 

changelog/tests/changelog/test_changelog_add.py

@@ -0,0 +1,80 @@
+import json
+
+from typer.testing import CliRunner
+
+from src.changelog import app
+
+runner = CliRunner()
+
+
+def _invoke_add(tmp_path, domain="database", entry_type="bug", message="A test fix", issue="42"):
+    return runner.invoke(
+        app,
+        [
+            "add",
+            "--working-dir", str(tmp_path),
+            "--domain", domain,
+            "--type", entry_type,
+            "--message", message,
+            "--issue", issue,
+        ],
+    )
+
+
+def test_add_creates_entry_file(tmp_path):
+    result = _invoke_add(tmp_path)
+    assert result.exit_code == 0
+    file_path = result.output.strip()
+    assert file_path.endswith(".json")
+    with open(file_path) as f:
+        entry = json.load(f)
+    assert entry["message"] == "A test fix"
+    assert entry["domain"] == "database"
+
+
+def test_add_includes_issue_number(tmp_path):
+    result = _invoke_add(tmp_path, issue="99")
+    assert result.exit_code == 0
+    file_path = result.output.strip()
+    with open(file_path) as f:
+        entry = json.load(f)
+    assert entry["issue_number"] == 99
+
+
+def test_add_without_issue(tmp_path):
+    result = _invoke_add(tmp_path, issue="")
+    assert result.exit_code == 0
+    file_path = result.output.strip()
+    with open(file_path) as f:
+        entry = json.load(f)
+    assert entry.get("issue_number") is None
+
+
+def test_add_invalid_domain(tmp_path):
+    result = _invoke_add(tmp_path, domain="not_a_real_domain")
+    assert result.exit_code != 0
+
+
+def test_add_invalid_type(tmp_path):
+    result = _invoke_add(tmp_path, entry_type="not_a_real_type")
+    assert result.exit_code != 0
+
+
+def test_add_invalid_issue(tmp_path):
+    result = _invoke_add(tmp_path, issue="not-a-number")
+    assert result.exit_code != 0
+
+
+def test_add_without_issue_flag_runs_noninteractively(tmp_path):
+    result = runner.invoke(
+        app,
+        [
+            "add",
+            "--working-dir", str(tmp_path),
+            "--domain", "database",
+            "--type", "bug",
+            "--message", "A test fix",
+        ],
+    )
+    assert result.exit_code == 0
+    assert result.output.strip().endswith(".json")

justfile

@@ -1175,10 +1175,11 @@ env-clear:
     fi
 
 # Run changelog command (e.g., just changelog add, just changelog release 2.3.0)
+[positional-arguments]
 [group('5 - utilities')]
 [doc("Changelog: just changelog <add|release|generate|purge>")]
 changelog *args:
-    cd backend && uv run --group changelog python ../changelog/src/changelog.py {{ args }}
+    cd backend && uv run --group changelog python ../changelog/src/changelog.py "$@"
 
 # Run changelog tests
 [group('4 - testing')]