#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.

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.

#publication_probe

def publication_probe(self, dir_path: str, version: str, ctx=None)

Probe the registry to determine if a specific version is published.

Returns a PublicationProbeResult (PUBLISHED, UNPUBLISHED, or UNPROBEABLE). Default: UNPROBEABLE.

#build

def build(self, dir_path: str, version: str, *, config: dict | None=None) -> 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, 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.

The returned dict may also carry an optional top-level "reason" key: a human-readable explanation for why the modes are None (e.g. "Go library: nothing to install"). rlsbl dev install surfaces it in the skip message instead of the generic "not yet supported" line.

#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)

Return the relative path of the file that holds the project version.

#tag_format

def tag_format(self, version)

Return the git tag string for a standalone release version.

#monorepo_tag_format

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

Return the git tag string for a monorepo package release.

#monorepo_tag_glob

def monorepo_tag_glob(self, name, path=None)

Return a glob pattern matching all version tags for a monorepo package.

#template_dir

def template_dir(self)

Return the path to this target's ecosystem-specific template directory.

#shared_template_dir

def shared_template_dir(self)

Return the path to the shared template directory common to all targets.

#read_name

def read_name(self, dir_path, ctx)

Read the project name from the target's manifest file.

#read_metadata

def read_metadata(self, dir_path)

Read project metadata (license, description) from the manifest file.

#template_vars

def template_vars(self, dir_path, ctx)

Return template variables extracted from the project for scaffold rendering.

#template_mappings

def template_mappings(self, ctx)

Return the list of target-specific template-to-file mappings for scaffolding.

#shared_template_mappings

def shared_template_mappings(self, ctx)

Return template-to-file mappings shared across all targets.

#_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)

Return True if the project's manifest file exists in dir_path.

#get_project_init_hint

def get_project_init_hint(self)

Return a user-facing hint for initializing a project of this target type.

#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.

#_resolve_build_timeout

def _resolve_build_timeout(self, config)

Resolve the build timeout from config, then the shipped default.

1. config["build_timeout"] -- an int, or a dict keyed by target

name with an optional "default" entry

1. self.BUILD_TIMEOUT_DEFAULT class variable

There is deliberately no environment-variable layer: build budgets are declared in .rlsbl/config.json, never picked up from the ambient environment.

#build

def build(self, dir_path, version, *, config=None)

Build distributable artifacts for this target. No-op by default.

#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, 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.

#publication_probe

def publication_probe(self, dir_path, version, ctx=None)

Probe the registry to determine if a specific version is published.

Returns a PublicationProbeResult with one of three statuses: PUBLISHED: the version exists on the registry. UNPUBLISHED: the version does not exist on the registry. UNPROBEABLE: this target cannot probe (no API, no name, etc.).

The default implementation returns UNPROBEABLE. Targets with registry APIs (npm, pypi, go) override this to query the registry.

#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 via go list (any package main package, regardless of file names or layout)
• GoReleaser integration for binary projects; library projects need no publish step. Ambiguous multi-main layouts require install_paths on the go pipeline config.
• npm binary wrapper support, activated with {"npm_wrapper": {"enabled": true}} in .rlsbl/config.json. Per-platform packages publish under bare suffixed names (<bin>-linux-x64, <bin>-darwin-arm64, ...) plus a meta wrapper named <bin>. Scoped npm names (@scope/name) are banned by ecosystem policy; each bare per-platform name must be independently approved (rlsbl check-name) like any other package name. A stale npm_wrapper.scope/npm_scope key is a hard error.
• Homebrew tap support via homebrew config
• dev_install: go install <install_paths> from the go pipeline config (no venv concept); undeclared install_paths is a hard error

#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

#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, activated with {"npm_wrapper": {"enabled": true}}. Publishes bare per-platform names (<bin>-linux-x64, ...) plus a meta wrapper named <bin>; scoped names are banned and each name needs explicit rlsbl check-name approval. A stale npm_wrapper.scope/npm_scope key is a hard error.
• 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 16 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.

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)

Return the relative path of the file that holds the project version.

#tag_format

def tag_format(self, version)

Return the git tag string for a standalone release version.

#monorepo_tag_format

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

Return the git tag string for a monorepo package release.

#monorepo_tag_glob

def monorepo_tag_glob(self, name, path=None)

Return a glob pattern matching all version tags for a monorepo package.

#template_dir

def template_dir(self)

Return the path to this target's ecosystem-specific template directory.

#shared_template_dir

def shared_template_dir(self)

Return the path to the shared template directory common to all targets.

#read_name

def read_name(self, dir_path, ctx)

Read the project name from the target's manifest file.

#read_metadata

def read_metadata(self, dir_path)

Read project metadata (license, description) from the manifest file.

#template_vars

def template_vars(self, dir_path, ctx)

Return template variables extracted from the project for scaffold rendering.

#template_mappings

def template_mappings(self, ctx)

Return the list of target-specific template-to-file mappings for scaffolding.

#shared_template_mappings

def shared_template_mappings(self, ctx)

Return template-to-file mappings shared across all targets.

#_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)

Return True if the project's manifest file exists in dir_path.

#get_project_init_hint

def get_project_init_hint(self)

Return a user-facing hint for initializing a project of this target type.

#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.

#_resolve_build_timeout

def _resolve_build_timeout(self, config)

Resolve the build timeout from config, then the shipped default.

1. config["build_timeout"] -- an int, or a dict keyed by target

name with an optional "default" entry

1. self.BUILD_TIMEOUT_DEFAULT class variable

There is deliberately no environment-variable layer: build budgets are declared in .rlsbl/config.json, never picked up from the ambient environment.

#build

def build(self, dir_path, version, *, config=None)

Build distributable artifacts for this target. No-op by default.

#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, 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.

#publication_probe

def publication_probe(self, dir_path, version, ctx=None)

Probe the registry to determine if a specific version is published.

Returns a PublicationProbeResult with one of three statuses: PUBLISHED: the version exists on the registry. UNPUBLISHED: the version does not exist on the registry. UNPROBEABLE: this target cannot probe (no API, no name, etc.).

The default implementation returns UNPROBEABLE. Targets with registry APIs (npm, pypi, go) override this to query the registry.

#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).