Release Please & Automations
Relevant source files
The following files were used as context for generating this wiki page:
Kocteau utilizes automated release management via Release Please to maintain its versioning and changelog consistency. The system is designed to remove the manual burden from contributors by deriving version bumps and release notes directly from Pull Request titles and squash commit messages.
This automation ensures that every change landing on the main branch is properly categorized, documented in the CHANGELOG.md, and tagged within the repository. Within the project ecosystem, this relates closely to the Product Roadmap and contributor workflows.
Sources: CONTRIBUTING.md:68-71, README.md:231-233
Automated Release Workflow
The release process is triggered by Pull Requests. Contributors are required to use specific PR title formats, which Release Please parses to determine the impact of the change (e.g., feature, fix, or breaking change).
Conventional Commits & PR Titles
Kocteau follows the Conventional Commits specification. This allows the automation to automatically update versions and generate release notes without manual intervention.
| Type | Purpose | Resulting Version Bump |
|---|---|---|
feat | New features | Minor |
fix | Bug fixes | Patch |
perf | Performance improvements | Patch |
docs | Documentation changes | Patch (or none depending on config) |
refactor | Code refactoring | Patch |
chore | Maintenance tasks | None (usually hidden from changelog) |
Sources: release-please-config.json:11-53, CONTRIBUTING.md:73-78
Lifecycle of a Release
When changes land on the main branch, Release Please monitors the commit history. It maintains a "Release PR" that accumulates pending changes. Once a maintainer merges this Release PR, the automation performs the final tagging and publishing.
The diagram above shows the lifecycle from a contributor's initial Pull Request to the automated creation of a GitHub Release.
Sources: CONTRIBUTING.md:96-98, README.md:231-233
Configuration and Components
The release automation is governed by a central configuration file and supported by repository-wide scripts.
Release Please Configuration
The release-please-config.json file defines how the automation behaves, including which commit types are visible in the changelog and how tags are formatted.
{
"release-type": "node",
"include-component-in-tag": false,
"include-v-in-tag": true,
"bump-minor-pre-major": true,
"bump-patch-for-minor-pre-major": true,
"packages": {
".": {
"changelog-path": "CHANGELOG.md",
"pull-request-title-pattern": "chore(release): v${version}"
}
}
}
Sources: release-please-config.json:4-10, release-please-config.json:54-59
Changelog Integration
While CHANGELOG.md at the root is managed by Release Please, the web application also features a public-facing changelog at /help/changelog. This is managed via MDX entries located in apps/web/content/changelog/.
A specific script is provided in the web package to assist in drafting these entries:
- Command:
pnpm --filter web changelog:draft - Location:
apps/web/package.json
Sources: apps/web/package.json:9, apps/web/content/changelog/entries.ts:1-12
Repository Automation Scripts
The root package.json contains several automation scripts that facilitate development and maintenance of the environment, which is critical for consistent releases.
Core Automation Scripts
| Script | Command | Description |
|---|---|---|
supabase:types | node supabase/scripts/generate-types.mjs | Generates TypeScript types from the local DB |
check | pnpm lint && pnpm --filter web build | Comprehensive check for CI/CD readiness |
curate:starter:draft | node supabase/scripts/create-starter-curation-draft.mjs | Drafts editorial starter picks |
build | turbo run build | Orchestrates builds across the monorepo |
Sources: package.json:25-41
Monorepo Management
Kocteau uses Turborepo (configured via turbo) to manage task execution across apps/ and packages/. This ensures that linting and building steps—required before any release can be finalized—are executed efficiently across the workspace.
This sequence illustrates how build automation interacts with the manual maintainer review before the final release tagging.
Sources: package.json:40-41, apps/web/package.json:7
Summary
Release Please & Automations provide a structured, low-friction path for evolving the Kocteau codebase. By enforcing Conventional Commits and leveraging Turborepo for builds, the project maintains high standards for its public changelog and versioning history. Contributors simply need to provide clear, categorized PR titles, while the system handles the complexities of release coordination.