thi-ng / monopub

Lightweight & fast monorepo publish/release/changelog manager to automate releases using nothing more than Conventional Commits.

@thi.ng/monopub

Lightweight, simple & fast monorepo publish/release/changelog manager to automate releases using nothing more than Conventional Commits.

Status

stable - used in production

Currently implemented:

• Detailed Git commit parsing, filtering & analysis
  • Filter by file ext
  • Package name aliases (to assign commits from old pkg names)
• Computing packages touched by recent commits (or allow forcing all)
• Dependency graph construction for monorepo internal packages (incl. topological sort)
• Computing new package versions (based on Conventional Commit types used)
• Selective changelog creation (as Markdown files)
  • Commit type config
• Repo/publish config via dotenv
• Update package files w/ version bumps
  • Update/bump deps in transitive dependents
  • Update yarn.lock prior to 'publish' commit
• Commit updated package, yarn.lock & changelog files
• Create & add release tags
• Push to git remote
• Inject gitHead into published package.json files
• Publish to registry
• Reset git head post-publish
• Add pre-checks
  • On clean release branch?
  • Valid npm login/auth?

Goals & Non-goals

The original aim of this project was to produce an as minimal as possible release workflow suitable for the thi.ng/umbrella monorepo (currently ~189 TypeScript projects/packages). Over the past 2+ years, this tool has been reliably used to handle ~180 releases (tens of thousands if you count individual package releases) and so I consider this goal reached. The tool is also a magnitude faster than my previous experience with Lerna. Version analysis, version bumping and changelog generation (all Conventional Commits based) for all ~190 packages in thi.ng/umbrella only takes ~2-3 seconds (max), unlike Lerna which regularly took 30+ secs for the same tasks (and produced worse changelogs)...

There are configuration options to allow this project being used with other (similarly structured) monorepo setups, however there's no desire to go down the usual route in JS-land of adding 100s of overly complicated options suitable for seemingly all use cases and then none...

If you're interested in utilizing this tool with your repo, but not sure how, please reach out via the issue tracker...

Usage

git clone https://github.com/thi-ng/monopub.git

cd monopub

yarn install
yarn build

bin/monopub --help

 █ █   █           │
██ █               │
 █ █ █ █   █ █ █ █ │ @thi.ng/monopub 1.0.0
 █ █ █ █ █ █ █ █ █ │ Monorepo publish/release/changelog manager
                 █ │
               █ █ │

usage: monopub CMD [OPTS] ...
       monopub [CMD] --help


Available commands:

    changelog ∷ Create/update changelogs
    release   ∷ Prepare and execute full release of all touched packages
    version   ∷ Compute & apply version bumps

Common:

-A key=val, --alias key=val         [multiple] Alias pkg names (old=new) (default: {})
--ext EXT                           [multiple] File types to consider for changes (comma separated) (default: [".+"])
--indent VAL                        Indentation for generated JSON files: "number", "tab" (default: "\t")
-p PATH, --repo-path PATH           Monorepo local path (default: "<missing>")
-u URL, --repo-url URL              Monorepo remote URL (default: "<missing>")
-r PATH, --root PATH                Relative package root dir in repo (default: "packages")
-s SCOPE, --scope SCOPE             Package scope (default: "<missing>")

Command: changelog

Note

See various packages in the thi.ng/umbrella monorepo for generated changelogs: example thi.ng/rstream changelog

Create/update changelogs

Flags:

-a, --all                           Process all packages, not just unreleased
--dry-run                           Dry run

Main:

-b NAME, --branch NAME              Remote Git branch for package links in changelog (default: "main")
-cc TYPE, --cc-types TYPE           [multiple] Only consider given Conventional Commit types for determining changes:
                                    "feat", "fix", "perf", "refactor", "build", "docs", "chore" (default:
                                    ["feat","fix","refactor","perf"])
--dump-spec PATH                    Write release spec to JSON file
-o PATH, --out-dir PATH             Output root dir (default: --repo-path)

Command: version

Compute & apply version bumps

Flags:

-a, --all                           Process all packages, not just unreleased
--dry-run                           Dry run

Main:

--dump-spec PATH                    Write release spec to JSON file
-o PATH, --out-dir PATH             Output root dir (default: --repo-path)

Command: release

Prepare and execute full release of all touched packages

Flags:

-a, --all                           Process all packages, not just unreleased
--dry-run                           Dry run

Main:

-cc TYPE, --cc-types TYPE           [multiple] Only consider given Conventional Commit types for determining changes:
                                    "feat", "fix", "perf", "refactor", "build", "docs", "chore" (default:
                                    ["feat","fix","refactor","perf"])
-cb NAME, --changelog-branch NAME   Remote Git branch for package links in changelog (default: "main")
--dump-spec PATH                    Write release spec to JSON file
--max-repeat INT                    Max attempts (default: 3)
-script CMD, --publish-script CMD   Publish script alias name (default: "pub")
-rb NAME, --release-branch NAME     Remote branch name for publishing releases (default: "main")
-t INT, --throttle INT              Delay time (in ms) between publishing each pkg (default: 0)

License

© 2021 - 2023 Karsten Schmidt // Apache Software License 2.0