DOCSEARCHbyAlgolia
Submit Docs

Knope

website·Indexed 32 days ago

https://knope.tech/

A tool for managing software releases, versioning, and changelogs. Knope automates the process of bumping versions using semantic versioning, generating release notes from change files or conventional commits, and integrating with GitHub, Gitea, and Jira. It includes a CLI and a GitHub App (Knope Bot) to handle release workflows and documentation enforcement.

Tokens
21K
Snippets
108
Records
162
Agent score
65%

What's inside Knope

  1. Structure a Knope changelog file

    In Knope, a changelog is a Markdown file documenting user-relevant changes for a package, sorted from newest to oldest. It consists of an optional title, an optional introduction (used to explain versioning or breaking change definitions), and a series of version entries.
    # Changelog

This package follows semantic versioning. Breaking changes are defined as any change that requires a manual migration of configuration files.

## 2.0.0 (2023-02-01)
### Breaking changes
- A breaking change

## 1.2.3 (2022-12-03)
### Fixes
- A simple fix

  2. Understand the role of Change Files in versioning

    A change file is a specially formatted Markdown file located in the .changeset directory. These files serve two primary purposes: determining the next version of a project and generating the project's changelog. The collective set of these files is referred to as a 'changeset'.

  3. Understand how Knope generates release notes

    Knope generates consistent release notes for both changelogs (markdown files containing full version history) and forge releases (e.g., GitHub tagged releases) from the same source data. The primary difference is formatting: changelogs use smaller headers for versioning, while forge releases move the version number and date into the platform's title attribute rather than the markdown body.

  4. Understand the Step concept in workflows

    A Step is the smallest atomic unit of a workflow. Workflows are composed of these steps to execute a sequence of operations. Detailed definitions and available options for every possible step can be found in the configuration reference.

  5. Understand how Knope uses ChangeSets for releases

    A ChangeSet is a collection of change files located in the .changeset directory. During the release process, Knope aggregates all change files within the changeset—and integrates them with any conventional commits—to determine the next version for each package and to generate the project's changelog.

  6. Understand Forge integrations in Knope

    In Knope, a 'forge' refers to a full-featured Git server that provides a web interface (similar to GitHub, Gitea, or GitLab). Knope can interact with these platforms to manage Git-based workflows. Currently, Knope supports integration with GitHub and Gitea.

  7. Understand Knope package and versioning concepts

    In Knope, a package is a piece of software intended for release. A single package is defined by a single version number that must be consistent across all its manifest files. For example, if a package is released on multiple platforms, the version number must be identical in Cargo.toml (Rust), package.json (NPM), and deno.json or deno.jsonc (JSR).

    To determine if files belong to one package or should be split into separate packages, verify if every change affecting one file always affects the others. If a component (e.g., a specific Rust crate) needs its own independent versioning, it should be treated as a separate package.

  8. Understand what constitutes a 'change' in Knope

    In Knope, a 'change' is a single modification between releases that is relevant to the end-user. Changes are used to generate release notes and determine the package's semantic version. A single Git commit can contain zero, one, or multiple changes. Changes can be documented using either a change file or a conventional commit.

  9. Install and set up Knope Bot on GitHub

    To begin using Knope for release management, create a GitHub repository (with a README file) and install the Knope Bot from the GitHub Marketplace. It is recommended to use the "Only select repositories" option during installation to limit the bot's access to specific projects.

  10. Convert a single-package repository to a Knope monorepo

    To convert a single-package repository to a monorepo, follow these steps:

    1. Reorganize the repository: Move the existing package code from the root to a subdirectory (e.g., move root files to crates/package-name).
    2. Update knope.toml: Replace the global [package] section with a package-specific [packages.<package-name>] section. Update the paths for versioned_files and changelog to reflect the new directory structure.
    3. Create a monorepo-style tag: Because monorepo tagging differs from single-package tagging, create a new tag using the <package-name>/<version> syntax to ensure Knope can track future releases correctly.
    4. Add new packages: Create additional [packages.<package-name>] sections in knope.toml for new packages. Each new package must have an initial version tag (e.g., package-name/v0.0.0) to prevent Knope from including commits created before the package existed in its first release.

  11. Trigger release workflows using Knope Bot release branches

    To automate post-release tasks (such as publishing to a package manager or building binaries), use a GitHub Action triggered by the closure of a pull request from the knope/release branch into main. This is preferred over the on: release event because it reliably detects releases even when they are created as drafts. The workflow should check if the head reference is knope/release and if the pull request was merged, or if the workflow was triggered manually via workflow_dispatch.
    name: Release
on:
  pull_request:
    types: [closed]
    branches: [main]
  workflow_dispatch:
jobs:
  release:
    if: (github.head_ref == 'knope/release' && github.event.pull_request.merged == true) || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      # Your release steps here

  12. Automate release PR creation with GitHub Actions

    Create a GitHub Action workflow at .github/workflows/prepare_release.yaml to trigger the Knope prepare-release workflow on every push to the main branch. This requires a Personal Access Token (PAT) with permissions to read repository contents and write pull requests.
    on:
  push:
    branches: [main]

name: Create Release PR

jobs:
  prepare-release:
    if: "!contains(github.event.head_commit.message, 'chore: prepare release')"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.PAT }}
      - name: Configure Git
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "github-actions@github.com"
      - uses: knope-dev/action@v2.1.2
        with:
          version: 0.23.0
      - run: knope prepare-release --verbose
        env:
          GITHUB_TOKEN: ${{ secrets.PAT }}
        continue-on-error: true