# conjikidow/bump-version architecture

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

- Interactive diagram: https://gitdiagram.com/conjikidow/bump-version
- Repository: https://github.com/conjikidow/bump-version

## Overview

##### Project type and purpose
- This is a GitHub Action (“Bump Version by Labels”) designed to run in the GitHub Actions environment.
- Purpose: Automatically bump the semantic version of a project based on pull-request labels, open a version-bump PR, and, once merged, push new Git tags.

##### File structure
- Top-level:
- `.bumpversion.toml` – configuration for bump-my-version
- `action.yaml` – GitHub Action metadata (inputs, outputs, entrypoint)
- `README.md`, `LICENSE`
- `.github/` folder:
- `workflows/ci.yaml`, `bump-version.yaml`, etc. – CI definitions and test workflows
- `labels/` & related files – label definitions for automatic PR labeling
- `src/` folder:
- `determine-bump-type.sh` – reads PR labels, decides bump type (major/minor/patch)
- `bump-version.sh` – invokes bump-my-version to update files
- `create-tag.sh` – after merge, parses branch name and pushes Git tags

##### README for additional insights
- Triggers on `pull_request.closed` when PR is merged.
- Uses GitHub API to read labels, create branches, open PRs, write tags.
- Delegates version file updates to `bump-my-version`.
- Enforces semantic versioning rules and manages major/minor/patch tags.

##### Main components & their interactions
a. GitHub Events (pull_request.closed)
b. GitHub Actions Runner
c. Entry point (`action.yaml`)
d. Shell scripts in `src/`:
- -bump-type.sh
- bump-version.sh
- create-tag.sh
e. External tool: `bump-my-version`
f. GitHub API for branch creation, PR creation, tag pushes
g. Configuration file: `.bumpversion.toml`
h. Git repository (files to be updated/tagged)

Interaction flow:
1. GitHub Event → triggers Action on the runner
2. Runner loads inputs from `action.yaml` and `.bumpversion.toml`
3. `determine-bump-type.sh` calls GitHub API to list PR labels → decides bump type
4. `bump-version.sh` invokes `bump-my-version` → updates version in target files
5. If version changed, script uses Git + GitHub API → creates new branch + opens version-bump PR
6. On merge, runner invokes `create-tag.sh` → extracts version, calls GitHub API → pushes `vX.Y.Z`, `vX.Y`, `vX` tags

##### Architectural patterns & principles
- Event-driven workflow (trigger/respond)
- Single Responsibility: each script has one clear task
- Configuration-driven (semantic version rules via `.bumpversion.toml`)
- API-driven integration with GitHub
- Idempotent operations: skip if no matching labels or if bump not needed

1. “GitHub Event: pull_request.closed (merged)” at the top.
a. -bump-type.sh → GitHub API (List labels) → Bump type decision
b. bump-version.sh → bump-my-version → modifies version files → Git commit → GitHub API (create branch + PR)
c. create-tag.sh (triggered on PR merge) → extract version → GitHub API (push tags)
4. `.bumpversion.toml` file feeding configuration into the bump-version step.
5. Git repository as storage for version-controlled files and tags.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Event Trigger
    Event["GitHub Event: pull_request.closed (merged)"]:::infra

    %% GitHub Workflows Configuration
    subgraph "GitHub Workflows"
        BW["bump-version.yaml"]:::config
        CI["ci.yaml"]:::config
        GL["generate-labels.yaml"]:::config
        LP["label-pr.yaml"]:::config
    end

    %% Label Definitions
    subgraph "Label Definitions"
        LabelDef["label-definition.yaml"]:::config
        Labeler["labeler.yaml"]:::config
    end

    %% Repository Metadata & Documentation
    subgraph "Repo Metadata"
        README["README.md"]:::config
        LICENSE["LICENSE"]:::config
        Codeowners["CODEOWNERS"]:::config
        Renovate["renovate.json5"]:::config
    end

    %% Runner and Scripts
    Event -->|"triggered by workflows"| Event
    BW -->|defines triggers| Event
    CI -->|runs tests| Event

    Event -->|"starts"| Runner["GitHub Actions Runner"]:::infra

    subgraph "GitHub Actions Runner"
        Entry["action.yaml"]:::config
        Determine["determine-bump-type.sh"]:::script
        Bump["bump-version.sh"]:::script
        Tag["create-tag.sh"]:::script
    end

    Runner --> Entry
    Entry --> Determine
    LabelDef --> Determine
    Labeler --> Determine

    Determine -->|"List PR labels"| API["GitHub API"]:::api
    API -->|"Return labels"| Determine
    Determine -->|"Decide bump type"| Bump

    Config[".bumpversion.toml"]:::config --> Bump
    Bump -->|"Invoke"| Tool["bump-my-version"]:::tool
    Tool -->|"Update version files"| Bump
    Bump -->|"Create branch & PR"| API
    API -->|"Branch created & PR opened"| Repo["Git Repository"]:::git

    Runner -->|"on PR merge"| Tag
    Tag -->|"Extract version & push tags"| API
    API -->|"Tags pushed (vX.Y.Z, vX.Y, vX)"| Repo

    %% Click Events
    click Entry "https://github.com/conjikidow/bump-version/blob/main/action.yaml"
    click Config "https://github.com/conjikidow/bump-version/blob/main/.bumpversion.toml"
    click Determine "https://github.com/conjikidow/bump-version/blob/main/src/determine-bump-type.sh"
    click Bump "https://github.com/conjikidow/bump-version/blob/main/src/bump-version.sh"
    click Tag "https://github.com/conjikidow/bump-version/blob/main/src/create-tag.sh"
    click BW "https://github.com/conjikidow/bump-version/blob/main/.github/workflows/bump-version.yaml"
    click CI "https://github.com/conjikidow/bump-version/blob/main/.github/workflows/ci.yaml"
    click GL "https://github.com/conjikidow/bump-version/blob/main/.github/workflows/generate-labels.yaml"
    click LP "https://github.com/conjikidow/bump-version/blob/main/.github/workflows/label-pr.yaml"
    click LabelDef "https://github.com/conjikidow/bump-version/blob/main/.github/labels/label-definition.yaml"
    click Labeler "https://github.com/conjikidow/bump-version/blob/main/.github/labels/labeler.yaml"
    click README "https://github.com/conjikidow/bump-version/blob/main/README.md"
    click LICENSE "https://github.com/conjikidow/bump-version/tree/main/LICENSE"
    click Codeowners "https://github.com/conjikidow/bump-version/tree/main/.github/CODEOWNERS"
    click Renovate "https://github.com/conjikidow/bump-version/blob/main/.github/renovate.json5"

    %% Styles
    classDef infra fill:#d0e7ff,stroke:#0366d6;
    classDef script fill:#e6ffed,stroke:#28a745;
    classDef config fill:#f0fff4,stroke:#22863a;
    classDef tool fill:#fff5b1,stroke:#d29922;
    classDef api fill:#f5e8ff,stroke:#6f42c1;
    classDef git fill:#fff0f6,stroke:#d6336c;
```
