DOCSEARCHbyAlgolia
Submit Docs

cocogitto

repository·main·Indexed 22 days ago

https://github.com/cocogitto/cocogitto

A CLI and GitOps toolbox for enforcing Conventional Commits and Semver specifications. It provides tools for automating version bumping, changelog generation, and commit validation via the `cog` CLI, as well as a GitHub app for pull request validation. Features include `cog bump` for automated versioning, `cog changelog` for markdown generation using tera templates, and `cog-doc` for generating JSON schemas and configuration references for `cog.toml`.

Tokens
24.1K
Snippets
98
Records
128
Agent score
76%

What's inside cocogitto

  1. Use Bump Profiles for Custom Hooks

    main

    Bump profiles allow you to define sets of hooks that run before or after a version bump. You can define global profiles in [bump_profiles] or override them within specific monorepo packages.

    BumpProfile Options:

    • pre_bump_hooks: A list of hooks to run before the bump command.
    • post_bump_hooks: A list of hooks to run after the bump command.

    Example Global Profile:

    [bump_profiles.production]
pre_bump_hooks = ["./scripts/pre-release.sh"]
post_bump_hooks = ["./scripts/post-release.sh"]

  2. Use the Version DSL for manifest updates

    main

    Cocogitto provides a Domain Specific Language (DSL) for manipulating version strings within hooks. This is useful for updating development branch manifests (e.g., Maven snapshots).

    Keywords:

    • version, version_tag, latest, latest_tag, package.

    Syntax:

    • {{keyword|default}}: Use a default if the keyword is unavailable.
    • {{keyword+increment}}: Increment a part of the version.
      • major, minor, patch.
      • Example: {{version+1minor}} or {{version+2major+1patch}}.
    • {{keyword+increment-label}}: Add pre-release or build metadata (e.g., -SNAPSHOT).
    # cog.toml
post_bump_hooks = [
    "git push",
    "git push origin {{version|1.0.0}}",
    "git checkout develop",
    "git rebase master",
    "mvn versions:set -DnewVersion={{version|1.0.0+minor-SNAPSHOT}}",
    "cog commit chore \"bump snapshot to {{version|1.0.0+1minor-SNAPSHOT}}\"",
    "git push",
]

  3. Automatic versioning for monorepos

    main

    In a monorepo, cog bump --auto follows a specific lifecycle to manage both individual package versions and a global repository version. The process is as follows:

    1. Package Version Calculation: Calculates the next version for each package based on commits affecting that package's content.
    2. Global Version Calculation: Calculates a global version based on package versions and commits not belonging to any specific package.
    3. Global Changelog: Appends global changes and the list of package versions to /CHANGELOG.md.
    4. Global Pre-bump Hooks: Executes global pre-bump hooks.
    5. Package Changelog: Appends changes for each package to {package_path}/CHANGELOG.md.
    6. Package Pre-bump Hooks: Executes per-package pre-bump hooks.
    7. Version Commit: Creates a single version commit containing all changes.
    8. Package Tagging: Creates a tag for each new package version on the version commit.
    9. Global Tagging: Creates a global git tag on the version commit.
    10. Package Post-bump Hooks: Executes per-package post-bump hooks.
    11. Global Post-bump Hooks: Executes global post-bump hooks.

  4. Perform monorepo bumps with cog bump

    main

    Use the following commands to manage versions in a monorepo:

    • Automatic Bump: cog bump --auto - This is the recommended method. It creates a tag per changed package and a global monorepo tag.
    • Manual Bump (Global Only): cog bump --minor, cog bump --major, cog bump --patch, or cog bump --version - These commands only bump the monorepo version and do not bump individual packages.
    • Manual Bump (Global + Packages): To bump both the monorepo and the packages manually, add the --include-packages flag to your manual bump command.
    • Single Package Bump: cog bump --package=my_package --auto - Creates a single package tag based on the latest package tag.
    # Recommended: Automatic bump for all changed packages and global version
cog bump --auto

# Manual bump for global version only
cog bump --patch

# Manual bump for both global version and packages
cog bump --patch --include-packages

# Bump a specific package automatically
cog bump --package=my_package --auto

  5. Configure Monorepo Dependency Resolution

    main

    In monorepos with inter-package dependencies, Cocogitto can automatically determine the correct bump order using a dependency resolver. This ensures that dependencies are bumped before the packages that depend on them (topological sorting).

    To enable this, configure the resolver under the [monorepo] section in your cog.toml and define your packages under [monorepo.packages].

    Supported Resolvers

    • Cargo: For Rust projects using Cargo.toml.
    • Maven: For Java projects using pom.xml.
    • Npm: For JavaScript/TypeScript projects using package.json.

    The resolver automatically detects the appropriate manifest files to determine relationships.

    [monorepo]
resolver = "Cargo"  # or "Maven", "Npm"

[monorepo.packages]
my-package = { path = "packages/my-package" }
my-dependency = { path = "packages/my-dependency" }

  6. Migrate monorepo configuration from 6.5.0 to 7.0.0

    main

    In Cocogitto 7.0.0, the monorepo packages configuration was moved from the top-level [packages] key to a nested [monorepo.packages] key in cog.toml. If you are using monorepo features, you must update your configuration to avoid errors like No packages found.

    # After 7.0.0
[monorepo.packages]
my-package = { path = "crates/my-package", changelog_path = "crates/my-package/CHANGELOG.md" }
another-package = { path = "crates/another-package" }

  7. Install shell completions for cog

    main

    You can generate shell completions for bash, fish, and zsh. Note that the official Archlinux package may already include these.

    • Bash: Save to ~/.local/share/bash-completion/completions/cog.bash-completion.
    • Bash (macOS/Homebrew): Save to $(brew --prefix)/etc/bash_completion.d/cog.bash-completion.
    • Fish: Save to ~/.config/fish/completions/cog.fish.
    • Zsh: Save to ~/.zfunc/_cog.
    # Bash
cog generate-completions bash > ~/.local/share/bash-completion/completions/cog.bash-completion

# Bash (macOS/Homebrew)
cog generate-completions bash > $(brew --prefix)/etc/bash_completion.d/cog.bash-completion

# Fish
mkdir -p ~/.config/fish/completions
cog generate-completions fish > ~/.config/fish/completions/cog.fish

# Zsh
cog generate-completions zsh > ~/.zfunc/_cog

  8. Automatic versioning with `cog bump`

    main

    Cocogitto automates project versioning and changelog updates using the cog bump command. The process follows these steps:

    1. Calculate version: Determines the next version based on commit types since the last tag.
    2. Pre-bump hooks: Executes user-defined commands (e.g., building or manifest updates).
    3. Changelog update: Appends changes to CHANGELOG.md.
    4. Version commit: Creates a commit containing the changelog and version changes.
    5. Git tag: Creates a tag on the version commit.
    6. Post-bump hooks: Executes user-defined commands (e.g., pushing to remote or publishing packages).

    Note on 0.y.z versions: When using --auto, Cocogitto will never automatically bump to 1.0.0, even if there are breaking changes. This allows you to maintain a development stage before deciding when the API is stable.

    cog bump --auto

  9. Rollback strategy for Cocogitto migrations

    main

    If you encounter issues during a migration, follow these steps to revert:

    1. Keep old version: Do not uninstall the previous version of Cocogitto until the migration is fully verified and complete.
    2. Revert configuration: Use the backups of your configuration files created before the migration.
    3. Test thoroughly: Verify all workflows work in your local environment before deploying changes to production.

  10. Create conventional commits with `cog commit`

    main

    Use the cog commit command to create commits that follow the Conventional Commits specification. This ensures your commit history is structured and compatible with automated changelog generation.

    All cog commit subcommands follow this positional argument structure:

    cog commit [FLAGS] <type> <message> [scope]

    Note: The scope is passed as a positional argument after the message, which simplifies usage compared to standard git flags.

    Supported default types:

    • feat (features)
    • fix (bug fixes)
    • style (formatting, missing semi-colons, etc)
    • build (changes that affect the build system or external dependencies)
    • refactor (code changes that neither fix a bug nor add a feature)
    • ci (CI configuration files and scripts)
    • test (adding missing tests, refactoring tests)
    • perf (code changes that improve performance)
    • chore (other changes that don't modify src or test files)
    • revert (reverting a previous commit)
    • docs (documentation changes)
    # Example: creating 'feat: add awesome feature'
cog commit feat "add awesome feature"

# Example: creating 'feat(api): add awesome feature'
cog commit feat "add awesome feature" api

  11. Install Cocogitto

    main

    Cocogitto can be installed via several package managers depending on your operating system or environment:

    • Arch Linux: pacman -S cocogitto
    • Cargo (Rust): cargo install --locked cocogitto
    • Mise: mise use -g cocogitto@latest
    • NixOS: nix-env -iA cocogitto
    • Void Linux: xbps-install cocogitto
    • macOS: brew install cocogitto
    cargo install --locked cocogitto

  12. Generate manpages for cog and its subcommands

    main

    You can generate manpages for the cog binary and all of its subcommands using a hidden subcommand. Provide a target directory as an argument; if the directory does not exist, it will be created automatically (similar to mkdir -p). The generated manpages will be saved as files within that directory.

    cog generate-manpages "${PWD}/gen"