#Release targets

rlsbl supports 18 release targets. Each target handles version reading, writing, and tag formatting for a specific ecosystem. Targets do not handle publishing — that is the responsibility of pipelines.

[selfdoc: custom directive 'table-targets' failed: No module named 'rlsbl']

All targets share core release functionality: version bumping, git tagging, and GitHub Release creation. The table above shows optional capabilities that vary by ecosystem.

#Target vs Pipeline

Targets and pipelines serve orthogonal purposes in the release flow. Targets handle versioning (reading and writing version strings in manifest files), while pipelines handle publishing (uploading artifacts to registries). This separation allows flexible combinations where the versioning ecosystem differs from the publish destination:

A project can have a target for versioning without a corresponding pipeline (e.g., Go libraries that need no publish step), or a pipeline type that differs from the target (e.g., an npm target with a cloudflare-pages pipeline for deployment).

#Auto-detection

When rlsbl release run, rlsbl scaffold, or rlsbl targets needs to know which targets apply, it calls detect_targets(dir_path) which scans the project directory for manifest files and applies content-based disambiguation when multiple targets could match. The detection logic follows two paths:

1. Explicit configuration — If .rlsbl/config.json contains a targets array, that list is authoritative. Each entry is either a string ("npm") or a dict with name and optional path (for subdirectory targets). Unknown target names are warned and skipped.

1. Auto-detection fallback — If no targets array exists in config, every registered target's detect() method is called against the directory. Targets that return True are included.

The auto_detectable ClassVar on each target controls detection behavior:

#Detection priority

When multiple targets could match the same manifest file (e.g., a project with both pubspec.yaml and a flutter: section, or build.gradle matching both native-android and maven), targets use content-based checks to disambiguate and ensure exactly one target claims each project:

• dart excludes projects where pubspec.yaml contains a flutter: key
• flutter requires pubspec.yaml with a flutter: key
• plain yields to any other target's manifest file
• native-android vs maven: both use build.gradle.kts/build.gradle, but native-android checks for com.android.application plugin declaration

#Detection files

Each of the 18 target classes declares a detection_files ClassVar listing the filenames whose presence triggers detection. These filenames are aggregated into the PROJECT_MANIFESTS set used by workspace-level checks to detect unregistered projects in a monorepo. The table below shows each target's detection files:

#The ReleaseTarget protocol

All 18 targets implement a runtime-checkable Protocol that defines the interface for version management, detection, tag formatting, and CI template generation. Each target provides concrete implementations for its ecosystem's conventions. The key methods:

#rlsbl.targets.protocol

Release target protocol defining the formal interface that all target implementations must satisfy for detection, versioning, and scaffolding.

#ReleaseTarget

Protocol defining a release target.

Targets handle version management, scaffolding templates, and optionally build/publish steps for a specific ecosystem (npm, pypi, go, codehome, docs, etc.)

#name

def name(self) -> str

Unique identifier for this target (e.g. 'npm', 'pypi', 'codehome').

#detect

def detect(self, dir_path: str) -> bool

Check if this target is present/applicable in the given directory.

#read_version

def read_version(self, dir_path: str) -> str

Read the current version from the target's manifest file.

#read_name

def read_name(self, dir_path: str, ctx) -> str | None

Read the project's package name from the manifest, or None.

#read_metadata

def read_metadata(self, dir_path: str) -> dict[str, str]

Read optional metadata (license, description) from the manifest.

#write_version

def write_version(self, dir_path: str, version: str, ctx) -> None

Write a new version to the target's manifest file (atomic).

#version_file

def version_file(self, dir_path: str | None=None) -> str | None

Filename that holds the version (e.g. 'package.json'), or None if inherited.

When dir_path is provided, implementations may resolve the filename dynamically (e.g. Deno choosing between deno.json and deno.jsonc).

#tag_format

def tag_format(self, version: str) -> str

Format the git tag for a release. Returns f'v{version}' by default.

#monorepo_tag_format

def monorepo_tag_format(self, name: str, version: str, path: str | None=None) -> str

Format the git tag for a monorepo release. Default: f'{name}@v{version}'.

#monorepo_tag_glob

def monorepo_tag_glob(self, name: str, path: str | None=None) -> str

Return a glob pattern matching all monorepo version tags. Default: f'{name}@v*'.

#template_dir

def template_dir(self) -> str | None

Absolute path to target-specific template directory, or None.

#shared_template_dir

def shared_template_dir(self) -> str | None

Absolute path to shared template directory, or None.

#template_vars

def template_vars(self, dir_path: str, ctx) -> dict[str, str]

Extract template placeholder values from the project.

#template_mappings

def template_mappings(self, ctx) -> list[dict[str, str]]

Target-specific template-to-output-path mappings.

#shared_template_mappings

def shared_template_mappings(self, ctx) -> list[dict[str, str]]

Shared template-to-output-path mappings.

#check_project_exists

def check_project_exists(self, dir_path: str) -> bool

Check if the target's project file exists (alias for detect).

#get_project_init_hint

def get_project_init_hint(self) -> str

Human-readable hint for initializing a project for this target.

#build

def build(self, dir_path: str, version: str) -> None

Pre-publish build step (e.g. generate docs). No-op by default.

#dev_install_command

def dev_install_command(self, project_dir: str) -> dict[str, dict | None]

Return the local-install specs for this target, keyed by mode.

Used by rlsbl dev install to install/uninstall the project for local development. Returns a dict with two keys:

"global": spec for the global-install mode, where the project is installed as a globally-available tool or symlink (e.g. uv tool install -e ., npm link, go install). None if the target has no global-install concept.

"venv": spec for the local/venv-install mode, where dependencies are fetched into the project's own environment without exposing a global CLI (e.g. uv sync, npm install). None for targets that have no separate local-environment concept (e.g. Go, Cargo, Zig, Swift).

Each spec dict has the shape: { "tool": "uv", "args": ["tool", "install", "-e", "."], "uninstall_args_template": ["tool", "uninstall", "{name}"], "purpose": "for editable Python install", }

Fields: tool: CLI tool that must be on PATH. args: argv passed to the tool to install. uninstall_args_template: argv list of templates passed to the tool to uninstall. Each entry may contain {name} (replaced with the project's package name) or {dir} (replaced with the project directory basename). None means uninstall is not supported for this mode of this target. purpose: human-readable string for the require_tool error message.

#BaseTarget defaults

All concrete targets extend BaseTarget, which provides sensible defaults for common operations so that individual targets only need to override ecosystem-specific behavior. The base class handles tag formatting, shared template mappings, and stub implementations for optional methods:

• Tag format: v{version} (standalone) / {name}@v{version} (monorepo)
• Shared template mappings: CHANGELOG.md, .gitignore, hooks, lint configs, unreleased.jsonl
• No-op stubs for build(), dev_install_command(), read_name(), read_metadata()
• check_project_exists() delegates to detect()

Individual targets override only the methods specific to their ecosystem.

#rlsbl.targets.base

Base class for release targets providing shared defaults for version reading, writing, detection, scaffolding, and publish configuration.

#TemplateVars

Dict subclass that auto-generates namespaced {target}.{key} entries.

On construction, for every key in base_dict, an additional entry "{target_name}.{key}" is stored so templates can reference target-specific values like {{pypi.minRequiredPython}}.

Post-construction mutations (tv["newkey"] = val) produce bare-only keys -- this is correct for non-target-specific additions like year or repoName that callers add after the target returns its vars.

#BaseTarget

Concrete base providing defaults for optional Protocol methods.

Subclasses should override detection_files with the filenames whose existence in a directory indicates a project of that type. The tuple is used both by the target's own detect() method and by checks.PROJECT_MANIFESTS (derived automatically from the registry).

#name

def name(self)

Target registry name. Subclasses must override.

#version_file

def version_file(self, dir_path=None)

#tag_format

def tag_format(self, version)

#monorepo_tag_format

def monorepo_tag_format(self, name, version, path=None)

#monorepo_tag_glob

def monorepo_tag_glob(self, name, path=None)

#template_dir

def template_dir(self)

#shared_template_dir

def shared_template_dir(self)

#read_name

def read_name(self, dir_path, ctx)

#read_metadata

def read_metadata(self, dir_path)

#template_vars

def template_vars(self, dir_path, ctx)

#template_mappings

def template_mappings(self, ctx)

#shared_template_mappings

def shared_template_mappings(self, ctx)

#_lint_config_mappings

def _lint_config_mappings(self, ctx)

Return lint config mappings filtered by declared targets.

If no targets are configured, all 3 lint configs are included for backward compatibility with unconfigured projects.

#_extract_target_names

def _extract_target_names(ctx)

Extract target name strings from ctx.config["targets"].

Returns a set of target names, or an empty set if targets is not configured or ctx is unavailable.

#check_project_exists

def check_project_exists(self, dir_path)

#get_project_init_hint

def get_project_init_hint(self)

#write_version

def write_version(self, dir_path, version, ctx)

Write a new version to the target's version file(s).

Returns a list of relative file paths (relative to dir_path) that were modified. Subclasses must override this method and return the actual paths written.

#build

def build(self, dir_path, version)

#companion_tags

def companion_tags(self, name, version, path=None)

Return additional tags to create alongside the primary release tag.

Ecosystems that require extra tags (e.g. Go module proxy tags) override this to return a list of tag strings. The default implementation returns no companion tags.

Args:

• name: the releasable or project name.
• version: the version being released (without v prefix).
• path: workspace-relative path to the package directory, or

None for standalone projects.

Returns:

• List of tag strings to create alongside the primary tag.

#format_version

def format_version(self, version)

Format a semver version for this target's ecosystem.

The default implementation returns the version unchanged (identity). This is correct for npm, Go, Cargo, Deno, plain, and most targets where semver is used directly.

Targets with different version conventions (e.g. PyPI's PEP 440) override this to translate from semver to the ecosystem format.

#dev_install_command

def dev_install_command(self, project_dir)

Specs for local install via rlsbl dev install, keyed by mode.

Subclasses override to return spec dicts for the "global" and/or "venv" modes. See the protocol docstring for the spec format. Default returns {"global": None, "venv": None} (unsupported).

#Capabilities

Each target declares a capabilities frozenset containing zero or more capability strings that gate behavior in the release flow and check system. Commands and checks query these capabilities at runtime to determine which operations are valid for a given target:

Capabilities are checked at runtime. For example, rlsbl dev install skips targets without dev_install, and the name-consistency check skips targets without read_name.

#Ecosystem classification

Each target has an ecosystem string used for display and grouping in commands like rlsbl targets and rlsbl monorepo list. The 18 targets map to 18 distinct ecosystem labels, providing human-readable names for each registry and platform:

#Per-target notes

#npm

• Reads/writes package.json
• Detects package manager by walking up to git root looking for lock files: pnpm-lock.yaml (pnpm), yarn.lock (yarn), package-lock.json (npm), falls back to npm
• Package manager choice affects CI template selection (separate templates for pnpm and yarn)
• Extracts binCommand, repoName, registryUrl, publishSetup template variables
• dev_install: global via npm link, local via npm install

#pypi

• Reads/writes pyproject.toml (via tomlkit for comment preservation)
• Also bumps __version__ in {pkg_name}/__init__.py or src/{pkg_name}/__init__.py if present
• Build step handles monorepo path dependency rewriting (copies to temp dir, rewrites pyproject.toml, builds there)
• dev_install: global via uv tool install -e ., local via uv sync

#go

• Detection: go.mod presence
• Version stored in VERSION file (not go.mod — Go modules have no version field in go.mod)
• Monorepo tag format uses path prefix: {path}/v{version} (Go module proxy convention)
• Detects library vs binary projects (checks for package main in root files or cmd/ layout)
• GoReleaser integration for binary projects; library projects need no publish step
• npm binary wrapper support via npm_wrapper config
• Homebrew tap support via homebrew config
• dev_install: go install ./... (no venv concept)

#deno

• Handles both deno.json and deno.jsonc (prefers .json when both exist)
• For .jsonc files, uses regex-based version replacement to preserve comments
• For .json files, uses standard JSON rewrite preserving indent
• version_file() resolves dynamically based on which config file exists

#cargo

• Reads/writes Cargo.toml using tomlkit for round-trip editing
• dev_install: global via cargo install --path ., local via cargo build

#dart

• Reads/writes pubspec.yaml using ruamel.yaml for comment preservation
• Strips build number suffix (+N) when reading, handles it when writing
• Build number strategy configurable via build_number.enabled and build_number.strategy in config
• Excludes projects with flutter: key (those belong to the flutter target)

#flutter

• Extends DartTarget (inheritance, not duplication)
• Detection: pubspec.yaml must contain a flutter: key
• Inherits all dart version read/write logic including build number handling
• No detection_files of its own (shares pubspec.yaml with dart)

#swift

• Detection: Package.swift presence
• Version stored in VERSION file
• dev_install: global via swift build, no venv concept

#swift-apple

• Extends SwiftTarget (inheritance)
• Never auto-detected (auto_detectable = "no") — must be declared in .rlsbl/config.json targets array
• Provides macOS-only CI templates (uses macos-latest runners instead of ubuntu-latest)
• No dev_install support

#zig

• Detection: build.zig.zon or build.zig
• Version stored in VERSION file with automatic build.zig.zon synchronization
• npm binary wrapper support for cross-compiled binaries
• Cross-compilation target map for 6 platforms (linux/darwin/win32, x64/arm64)

#docker

• Detection: Dockerfile presence
• Version stored in VERSION file
• Image name derived from config (docker.image) or directory name

#maven

• Detection: build.gradle.kts, build.gradle, or pom.xml
• Supports three build systems: Maven (pom.xml), Gradle (build.gradle), Gradle Kotlin DSL (build.gradle.kts)

#spec

• Detection: version.json file presence
• Version: reads/writes {"version": "X.Y.Z"} in version.json
• Capabilities: read_name and ci_templates (a stub CI template for users to add their own validation commands) — no dev_install, no publish
• Use case: spec-only projects that need version tracking without any build or publish step — the tagged GitHub Release is the publication

#pgdesign

• Detection: pgdesign.toml file presence
• Version: reads/writes the version field in pgdesign.toml
• Capabilities: minimal — no ci_templates, no dev_install
• No publish mechanism — version bumping only (the tagged GitHub Release is the artifact)
• Use case: PostgreSQL schema design projects managed by the pgdesign tool

#native-ios

• Content-based detection: scans for .xcodeproj/project.pbxproj with MARKETING_VERSION
• Also supports Tuist Project.swift
• See native-targets.md for details

#native-android

• Content-based detection: checks build.gradle/build.gradle.kts for com.android.application plugin
• Manages both versionName (semver) and versionCode (integer, auto-incremented)
• See native-targets.md for details

#plain

• Detection: conditional — VERSION file must exist AND no other target manifest is present
• Version: reads/writes plain text VERSION file (single line, e.g. 0.5.2)
• Capabilities: none (zero capabilities — no read_name, no read_metadata, no ci_templates, no dev_install)
• Consequences of zero capabilities: no CI templates generated by scaffold, no rlsbl dev install support, no publish pipeline, no build_assets
• The exclusion list: plain will not auto-detect if any of the 17 other target manifests exist (package.json, pyproject.toml, go.mod, Cargo.toml, deno.json, deno.jsonc, mix.exs, build.gradle.kts, build.gradle, pom.xml, Package.swift, pubspec.yaml, Dockerfile, build.zig.zon, build.zig, version.json, pgdesign.toml)
• Use case: projects that need version tracking but don't fit any ecosystem (e.g., documentation-only repos, script collections, infrastructure projects)
• Also bumps pyproject.toml version if that file exists with a [project].version field

#Check support matrix

Some checks are universal (they run for any target), while others only apply to targets with language-specific import scanners or AST analysis. This matrix shows which target-specific checks support which targets.

[selfdoc: custom directive 'table-feature-matrix' failed: No module named 'rlsbl']

All checks not listed here are universal and run for every target.

#Target implementations

The base target class defines the shared interface for version reading, version writing, detection, and version file location. All 18 concrete target implementations inherit from this base and override the methods relevant to their ecosystem's versioning conventions.

#rlsbl.targets.base

Base class for release targets providing shared defaults for version reading, writing, detection, scaffolding, and publish configuration.

#TemplateVars

Dict subclass that auto-generates namespaced {target}.{key} entries.

On construction, for every key in base_dict, an additional entry "{target_name}.{key}" is stored so templates can reference target-specific values like {{pypi.minRequiredPython}}.

Post-construction mutations (tv["newkey"] = val) produce bare-only keys -- this is correct for non-target-specific additions like year or repoName that callers add after the target returns its vars.

#BaseTarget

Concrete base providing defaults for optional Protocol methods.

Subclasses should override detection_files with the filenames whose existence in a directory indicates a project of that type. The tuple is used both by the target's own detect() method and by checks.PROJECT_MANIFESTS (derived automatically from the registry).

#name

def name(self)

Target registry name. Subclasses must override.

#version_file

def version_file(self, dir_path=None)

#tag_format

def tag_format(self, version)

#monorepo_tag_format

def monorepo_tag_format(self, name, version, path=None)

#monorepo_tag_glob

def monorepo_tag_glob(self, name, path=None)

#template_dir

def template_dir(self)

#shared_template_dir

def shared_template_dir(self)

#read_name

def read_name(self, dir_path, ctx)

#read_metadata

def read_metadata(self, dir_path)

#template_vars

def template_vars(self, dir_path, ctx)

#template_mappings

def template_mappings(self, ctx)

#shared_template_mappings

def shared_template_mappings(self, ctx)

#_lint_config_mappings

def _lint_config_mappings(self, ctx)

Return lint config mappings filtered by declared targets.

If no targets are configured, all 3 lint configs are included for backward compatibility with unconfigured projects.

#_extract_target_names

def _extract_target_names(ctx)

Extract target name strings from ctx.config["targets"].

Returns a set of target names, or an empty set if targets is not configured or ctx is unavailable.

#check_project_exists

def check_project_exists(self, dir_path)

#get_project_init_hint

def get_project_init_hint(self)

#write_version

def write_version(self, dir_path, version, ctx)

Write a new version to the target's version file(s).

Returns a list of relative file paths (relative to dir_path) that were modified. Subclasses must override this method and return the actual paths written.

#build

def build(self, dir_path, version)

#companion_tags

def companion_tags(self, name, version, path=None)

Return additional tags to create alongside the primary release tag.

Ecosystems that require extra tags (e.g. Go module proxy tags) override this to return a list of tag strings. The default implementation returns no companion tags.

Args:

• name: the releasable or project name.
• version: the version being released (without v prefix).
• path: workspace-relative path to the package directory, or

None for standalone projects.

Returns:

• List of tag strings to create alongside the primary tag.

#format_version

def format_version(self, version)

Format a semver version for this target's ecosystem.

The default implementation returns the version unchanged (identity). This is correct for npm, Go, Cargo, Deno, plain, and most targets where semver is used directly.

Targets with different version conventions (e.g. PyPI's PEP 440) override this to translate from semver to the ecosystem format.

#dev_install_command

def dev_install_command(self, project_dir)

Specs for local install via rlsbl dev install, keyed by mode.

Subclasses override to return spec dicts for the "global" and/or "venv" modes. See the protocol docstring for the spec format. Default returns {"global": None, "venv": None} (unsupported).