# googleapis/release-please architecture

> Architecture diagram of the GitHub repository googleapis/release-please, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googleapis/release-please
- Repository: https://github.com/googleapis/release-please

## Overview

##### Project Type and Purpose
- This is a Node.js‐based CLI/library project (“release-please”) that automates changelog generation, version bumps, and GitHub release creation.
- It can run as a standalone CLI, a GitHub Action, or a Probot GitHub App.

##### High-Level File Structure Overview
- **src/**: core TypeScript code, subdivided into:
- bin/ (entrypoint)
- strategies/ (language‐specific release strategies)
- updaters/ (file‐format updaters: package.json, CHANGELOG.md, pom.xml, etc.)
- plugins/ (monorepo plugins, merge behavior, grouping, etc.)
- util/ (utility functions: commit parsing, logging, GitHub API helpers)
- versioning‐strategies/ (SemVer bump rules)
- factories/ (instantiate appropriate strategy/updater/plugin)
- templates/ (handlebars templates for commit entries, headers, PR bodies)
- **schemas/**: JSON schemas for manifest/config validation.
- **docs/**: design & usage guides.
- **test/** & **__snapshots__/**: unit/integration tests, fixtures.
- CI configs: **.github/workflows/**, **.kokoro/**.

##### Core Components & Their Roles
a. CLI / Entrypoint (`src/bin/release-please.ts`)
– Parses CLI flags, loads user config, invokes core engine.
b. Core Engine (`src/index.ts`, `bootstrapper.ts`, `update.ts`)
– Reads git history, determines releasable units, orchestrates strategy + updater + GitHub calls.
c. Strategy Layer (`src/strategies/*.ts`)
– Defines language‐specific release semantics (e.g. “node”, “java”, “rust”).
d. Updater Layer (`src/updaters/**/*.ts`)
– Modifies files on disk (CHANGELOG.md, package.json, pom.xml, etc.).
e. Plugin Layer (`src/plugins/*.ts`)
– Adds extensibility for multi‐package repos, grouping, merge ordering, linked versions.
f. Factories (`src/factories/*.ts`)
– At runtime, selects correct strategy/updater/plugin based on config or repository layout.
g. Utilities (`src/util/*.ts`)
– Commit parsing, templating, GitHub API wrappers, logging.
h. GitHub Interaction (`src/github.ts`, `src/pull-request.ts`)
– Creates PRs, labels, tags, releases via GitHub REST API.
i. Configuration & Schema (`schemas/`, `release-please-config.json`)
– Validates user manifest for multi-artifact repos.

##### External Dependencies
- **Git**: reads commit history, tags, branches.
- **GitHub API**: fetch repo data, create/label PRs, create releases, read files.
- **Filesystem**: reads/writes project files (CHANGELOG.md, metadata).
- **Templating**: Handlebars for changelog entries, headers.

##### Interactions & Data Flows
1. **User / CI Trigger** → CLI entrypoint → load config
2. Core Engine → Git (commit log since last tag)
3. Core Engine → Factory → choose Strategy + Updaters + Plugins
4. Strategy → identify version bump (major/minor/patch)
5. Updaters → modify files on disk (changelog, manifests, version files)
6. Core Engine → Git → commit changes, tag version
7. Core Engine → GitHub API → open or update Release PR with templated body
8. On PR merge → GitHub Action (or CLI rerun) → detect merged tag → create GitHub Release

##### Architectural Patterns & Principles
- **Strategy Pattern** for language‐specific rules.
- **Factory Pattern** to instantiate correct strategy/updaters/plugins.
- **Plugin Architecture** for monorepo extensions (cargo, maven, node-workspace).
- **Layered Design** separating CLI, core orchestration, domain logic, I/O, external API.
- **Schema Validation** for user manifests (robust configuration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Components
    CLI["CLI Entrypoint"]:::frontend
    CoreEngine["Core Engine / Orchestrator"]:::core
    GitClient["Git Client"]:::io
    GitHubClient["GitHub API Client"]:::frontend
    Filesystem["Filesystem"]:::io
    Config["Configuration / Schemas"]:::config

    subgraph "Core Logic Layers"
        Factories["Factories"]:::core
        Strategy["Strategy Module"]:::core
        Updater["Updater Module"]:::core
        Plugin["Plugin Module"]:::core
        Utilities["Utilities"]:::core
    end

    %% Flows
    CLI -->|"1. load config"| Config
    CLI -->|"1. invoke engine"| CoreEngine
    CoreEngine -->|"2. read commits"| GitClient
    CoreEngine -->|"3. select components"| Factories
    Factories -->|"instantiate"| Strategy
    Factories -->|"instantiate"| Updater
    Factories -->|"instantiate"| Plugin
    Strategy -->|"4. determine bump"| CoreEngine
    CoreEngine -->|"5. parse & template"| Utilities
    CoreEngine -->|"5. apply updates"| Updater
    Updater -->|"5. write files"| Filesystem
    CoreEngine -->|"6. commit & tag"| GitClient
    CoreEngine -->|"7. open/update PR"| GitHubClient
    GitHubClient -->|"8. on merge trigger"| CoreEngine
    CoreEngine -->|"8. create release"| GitHubClient

    %% Legend
    subgraph Legend
        A["Green: User-facing"]:::frontend
        B["Blue: Core logic"]:::core
        C["Yellow: I/O"]:::io
        D["Orange: Config"]:::config
    end

    %% Click Events
    click CLI "https://github.com/googleapis/release-please/blob/main/src/bin/release-please.ts"
    click CoreEngine "https://github.com/googleapis/release-please/blob/main/src/index.ts"
    click CoreEngine "https://github.com/googleapis/release-please/blob/main/src/bootstrapper.ts"
    click CoreEngine "https://github.com/googleapis/release-please/blob/main/src/update.ts"
    click Strategy "https://github.com/googleapis/release-please/tree/main/src/strategies/"
    click Updater "https://github.com/googleapis/release-please/tree/main/src/updaters/"
    click Plugin "https://github.com/googleapis/release-please/tree/main/src/plugins/"
    click Factories "https://github.com/googleapis/release-please/tree/main/src/factories/"
    click Utilities "https://github.com/googleapis/release-please/tree/main/src/util/"
    click GitHubClient "https://github.com/googleapis/release-please/blob/main/src/github.ts"
    click GitHubClient "https://github.com/googleapis/release-please/blob/main/src/pull-request.ts"
    click GitHubClient "https://github.com/googleapis/release-please/blob/main/src/release-pull-request.ts"
    click Config "https://github.com/googleapis/release-please/blob/main/schemas/config.json"
    click Config "https://github.com/googleapis/release-please/blob/main/schemas/manifest.json"
    click Config "https://github.com/googleapis/release-please/blob/main/release-please-config.json"
    click Config "https://github.com/googleapis/release-please/blob/main/.release-please-manifest.json"

    %% Styles
    classDef frontend fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef io fill:#fc6,stroke:#333,stroke-width:1px
    classDef config fill:#f96,stroke:#333,stroke-width:1px
```
