knope-dev/knope

A command line tool to to handle all the tasks most developers find tedious.

Knope

A command line tool that happily completes the tasks which most developers find tedious.

Example: Automating GitHub Actions Release

Got some conventional commits?

feat: A spicy feature
fix: Some sauce

And some changesets?

---
my-package: major
---

#### Big deal

You probably want to read this before upgrading 💜

Do you want to release this by hand? Knope! Here's a GitHub Actions workflow:

name: Drop a new version

on: workflow_dispatch

jobs:
  create-release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
          token: ${{ secrets.PAT }}
      - uses: knope-dev/action@v1 # Install Knope
        with:
          version: 0.7.4
      - run: knope release
        env:
          GITHUB_TOKEN: ${{ secrets.PAT }}

You get a GitHub release and a changelog, picking the semantic version based on the combination of conventional commits and changesets.

## 2.0.0

### Breaking Changes

#### Big deal

You probably want to read this before upgrading 💜

### Features

#### A spicy feature

### Fixes

#### Some sauce

Knope can do much more with some customization, read the docs for more info.

knope's Issues

RUSTSEC-2020-0016: `net2` crate has been deprecated; use `socket2` instead

net2 crate has been deprecated; use socket2 instead

Details
Status	unmaintained
Package	net2
Version	0.2.37
URL	deprecrated/net2-rs@3350e38
Date	2020-05-01

The net2 crate has been deprecated
and users are encouraged to considered socket2 instead.

See advisory page for additional details.

Add AssignJiraIssue Step

Usually if you're switching columns you also need to assign to someone. The simplest version is to code the name of the person to assign to into the config file.

Future versions might want to take this as a prompt? Or have multiple options with a dropdown?

Support Monorepos & Multiple Package Managers

The general idea is to have the scope of a conventional commit correlate to a specific package. Here's my current thinking:

• #148
• #149
• #151
• #26
• #152
• #153
• #154

Sample Non-Monorepo Config

This is what the dobby.toml for this repo might include after the change. This would preserve the existing behavior today, but be more explicit.

[[packages]]
versioned_files = ["Cargo.toml"]
changelog = "CHANGELOG.md"
version_prefix = "v."

Sample Monorepo Config

Here's an example config for a monorepo which contains both Rust and Python code which should be versioned separately (depending on the change) and released separately.

[[packages]]
versioned_files = ["python/pyproject.toml"]
changelog = "python/CHANGELOG.md"
scopes = ["python"]
version_prefix = "python@"

[[packages]]
versioned_files = ["rust/Cargo.toml"]
changelog = "rust/CHANGELOG.md"
scopes = ["rust"]
version_prefix = "rust@"

With that config, here are some commits and their effects:

1. feat: A new global feature: Bumps both python/pyproject.toml and rust/Cargo.toml with the "minor" semver rule. Adds an identical entry to both changelogs.
2. fix(something): a fix: Bumps both python/pyproject.toml and rust/Cargo.toml with the "patch" semver rule. Adds an identical entry to both changelogs. Scope is effectively ignored because it isn't registered.
3. feat(rust): Did something to Rust: only modifies rust/Cargo.toml and rust/CHANGELOG.md.
4. feat(python): Did something to Python: only modifies python/pyproject.toml and python/CHANGELOG.md.

So the rust/CHANGELOG.md would look something like this:

## 1.2.0 - 2021-02-11

### Features

- A new global feature
- Did something to Rust

### Fixes

- a fix

scopes should be optional so that if someone wants to version to two projects in lock-step (have every commit count toward both of them) then they can.

Add support for `go.mod`

Go modules are versioned differently than everything else Knope supports so far. Specifically, the versioned file (go.mod) only contains the major version, and only for major versions above 1. So, instead of using the versioned file as the source of truth for the version, the Git tag must be the source of truth. The format for the Git tag also has to be v{semver}. So, overall, the requirements for this are:

1. Support go.mod as a versioned file.
2. When go.mod is a versioned file—get the version from the latest Git tag which fits the required format. Consider that the version for this file.
3. When bumping the version—if the major version is bumped past 1—add/replace the version suffix in go.mod. Then commit that file.
4. When bumping the version, add a new tag to the current commit using the v{semver} syntax.

The real question is, should auto-commits be happening elsewhere as well? Should the step push to Git as well? None of the other versioned files are dependent on Git, so leaving that to the user is reasonable but maybe not the best UX?

Allow specifying path to changelog

Replace toml_edit

toml_edit is another fairly heavy dependency that I pulled in early to make dev easier. We can probably achieve the same thing with the normal toml lib which we also depend on, just gotta make sure we preserve key order so we don't break the same thing that Zak fixed in #75 .

Take in a version prefix to use with `Release` step.

Should be configured at the package level (#148). This will be useful in general for folks who want a version like v.1.2.3 as their tag, but also means that they could do [email protected] or something.

Instead of picking up the first package manager found, require the user to specify their versioned file.

This will enable specifying which file should be edited instead of the arbitrary "first" one being selected.

• When given a repo with all available metadata filetypes, only the selected one should be affected.
• No changelogs should be updated if not specified.
• When calling knope --generate, the first available metadata file (same order picked today) should be added as a package.
• When a PrepareRelease or BumpVersion step is called without a defined package—an error describing the recommended lines to add (the same thing --generate would output) should be returned to the user.
• More than one package specified should be an error pointing at #153
• More than one file in the package should be an error pointing at #149
• Update the docs to indicate the [[packages]] pre-req for associated steps including details about how changelog works.
• Throw a useful error when the listed file in [[packages]] versioned_files is not a supported format

Make selecting issues from branch names an explicit step

Today the only time we guess an issue key based on branch name is in the RebaseBranch step and we assume an issue type of Jira. I think instead this should be an explicit step where you have to specify which issue type you're going for.

This may be a good opportunity to make Issue a struct with a type field which is an enum since, although the names are different today, they effectively have the same fields.

Create & push a Git tag for `Release` rule without GitHub config.

Basically, a way to allow creating releases when GitHub is not configured. The Git tag will match the format of the one that would have been used for GitHub (v{version}).

PrepareRelease dry run

It'd be nice (in CI, in particular) to see what change notes and version changes would result from running PrepareRelease on the current set of commits without actually creating those changes.

If package-editing commands are run but no packages are manually configured, spit out suggested config in the output for existing users.

Is is to aid in the transition from 0.1 to 0.2

Detect knope.toml in parent directories

I'd like to be able to run dobby without having to be in the exact directory containing the dobby.toml. I may make the last git commit from a child directory, and it would smooth out the workflow to not need to cd.

A couple thoughts:

• This will include some sort of procdeural check through every parent directory
• We may want to stop searching after checking the root of the current git repository (git rev-parse --show-toplevel).
• What about git submodules where the submodule does not have a dobby.toml but the parent repo does?
• Should there be support for a global dobby.toml, e.g. at ~/.dobby.toml or ~/.config/dobby/dobby.toml? I don't see a need for it, but I am sure someone will come up with something.
• Related to the previous one: can settings cascade? Does it make sense for them to do so?

Special handling of 0.x versions

Convention is to bump minor for breaking changes and patch for non-breaking changes when the major version is 0.

Remove regex

regex is one of our next-heaviest dependencies that we could probably do without. I believe this is only used today to parse branch names to try and select issues from them, which should be easy enough to do from std methods.

Searching Jira issues fails if status contains a space

We probably just need to add quotes to JQL

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update dependency @astrojs/starlight to v0.24.4
• chore(deps): update rust crate changesets to 0.3.0
• chore(deps): update rust crate git2 to 0.19.0
• chore(deps): lock file maintenance
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

cargo

crates/knope-versioning/Cargo.toml

• itertools 0.13.0
• miette 7.2.0
• relative-path 1.9.3
• serde 1.0.200
• serde_json 1.0.116
• serde_yaml 0.9.34
• thiserror 1.0.59
• toml 0.8.12
• pretty_assertions 1.4.0

crates/knope/Cargo.toml

• base64 0.22.1
• changesets 0.2.3
• clap 4.5.4
• datta 0.1.1
• env_logger 0.11.3
• execute 0.2.13
• git2 0.18.3
• git-conventional 0.12.6
• gix 0.63.0
• indexmap 2.2.6
• inquire 0.7.5
• itertools 0.13.0
• log 0.4.21
• miette 7.2.0
• platform-dirs 0.3.0
• relative-path 1.9.3
• serde 1.0.200
• serde_json 1.0.116
• serde_yaml 0.9.34
• thiserror 1.0.59
• time 0.3.36
• toml 0.8.12
• ureq 2.9.6
• pretty_assertions 1.4.0
• snapbox 0.6.0
• tempfile 3.10.1

github-actions

.github/workflows/prepare_release.yml

• actions/checkout v4.1.7
• Swatinem/rust-cache v2

.github/workflows/release.yml

• actions/checkout v4.1.7
• Swatinem/rust-cache v2
• actions/upload-artifact v4.3.3
• actions/checkout v4.1.7
• actions/download-artifact v4.1.7
• Swatinem/rust-cache v2
• actions/checkout v4.1.7
• Swatinem/rust-cache v2
• katyo/publish-crates v2

.github/workflows/release_dry_run.yml

• actions/checkout v4.1.7
• Swatinem/rust-cache v2

.github/workflows/tests.yml

• actions/checkout v4.1.7
• Swatinem/rust-cache v2
• actions/setup-node v4
• actions/checkout v4

npm

docs/package.json

• @astrojs/check ^0.7.0
• @astrojs/starlight ^0.24.0
• astro ^4.0.3
• sharp ^0.33.0
• starlight-links-validator ^0.9.0
• typescript ^5.2.2
• prettier =3.3.2
• prettier-plugin-astro ^0.14.0

regex

rust-toolchain.toml

• rust 1.79.0

docs/src/content/docs/installation.mdx

• knope-dev/action v2.1.0

docs/src/content/docs/recipes/1-preview-releases-with-pull-requests.md

• actions/checkout v4.1.7
• knope-dev/action v2.1.0
• actions/checkout v4.1.7
• actions/download-artifact v4.1.7
• knope-dev/action v2.1.0
• actions/checkout v4.1.7
• Swatinem/rust-cache v2.7.3
• actions/upload-artifact v4.3.3
• actions/checkout v4.1.7
• actions/download-artifact v4.1.7
• knope-dev/action v2.1.0
• actions/checkout v4.1.7
• Swatinem/rust-cache v2.7.3
• katyo/publish-crates v2

docs/src/content/docs/recipes/workflow-dispatch-releases.md

• actions/checkout v4.1.7
• knope-dev/action v2.1.0
• actions/checkout v4.1.7
• Swatinem/rust-cache v2.7.3
• actions/upload-artifact v4.3.3
• actions/checkout v4.1.7
• actions/download-artifact v4.1.7
• knope-dev/action v2.1.0

---

• Check this box to trigger a request for Renovate to run again on this repository

Generate changelogs and semver from conventional commits

Should read all commit messages since the previous tag, use something like https://crates.io/crates/git-conventional to parse them, determine the next semver version automatically, bump the project to that version, and add a new section to the changelog using something like https://crates.io/crates/markdown

Add a way to validate dobby workflows before running them

Certains steps require other steps to run first—ideally these mistakes could be caught without attempting to run the workflow (and potentially failing partway through).

Replace octocrab

This dependency binds us to specific Tokio/Reqwest versions. I'd rather use async-std anyway, and we don't have that option. It also contains a ton of features we don't use.

The immediate solution would be to write our own requests for the few pieces of the GitHub API that we do use, although we need to weigh this against the possibility of adding more direct GitHub integrations.

We could also fork octocrab and make it compatible with async-std using a feature flag (if portability is the main concern).

`SwitchBranches` fails if there is a `.` in the branch name

Any step which creates a Git branch should normalize the name first. Probably should just be alphanumeric and -

Document the special 0.x version handling in user-facing docs

Currently I believe the changes in #65 are only documented in source which isn't the best.

Pre-release functions for UpdateProjectFromCommits

It could be nice to have a pre-release mode for this step which will bump the -rc. (or -alpha. or whatever) number and update the CHANGELOG. This way if you want to do intermediate releases with tags and such you can still use this step.

Nicer Docs

Right now the docs are very technical—organized more for how the config syntax looks rather than how the tool should be used. More useful examples and demos should be included before the, effectively, API docs.

Add a way to generate some starter dobby.toml for a project

Add opening a GitHub Pull Request to workflow

Okay to use the GH CLI for now, eventually we'll want this functionality built into Dobby itself.

Add command variable for issue branch

Should be able to get the generated issue branch name in a Command variable even if not on that branch currently.

Allow fetching knope.toml from a remote source

Usecase is that generally a team will have a common workflow with a couple specific tweaks for a project. So they should be able to inherit workflows from other sources, then add on their own in their file.

Update Lock Files

Right now, only the metadata file (Cargo.toml, pyproject.toml, package.json) is updated and not the equivalent lockfile (cargo.lock, poetry.lock, package-lock.json) (the last one might not keep the package version). This leaves inconsistencies that will get updated the next time a user does anything with the package which is less than ideal.

Any supported package manager (so Cargo, Poetry, and NPM right now) should not leave any work to-do after bumping a version.

Allow configuring GitHub secret via env var

The objective is to be able to do #133 from GitHub Actions.

Allow multiple versioned files in a normal repo (e.g., both a `Cargo.toml` and a `pyproject.toml`).

Bump all files when updating version. When reading versions, ensure they are all consistent or fail (don't guess).

Support Separate Breaking Change Message

A valid semantic commit can look like this:

feat: My shiny new feature

BREAKING CHANGE: Something that broken when implementing it

and should result in two changelog entries: the first for the feature itself and the second for the breaking change.

This is a thing we should support.

Switch to pulldown-cmark

It seems the markdown crate is not maintained, which means adding things to changelogs (e.g., ordered lists) can cause dobby to panic without any remedy available. Best course seems to be to switch to a different crate, the most promising of which I've seen is pulldown-cmark.

Take in a version prefix to use with `Release` step. This will be useful in general for folks who want a version like `v.1.2.3` as their tag, but also means that they could do `[email protected]` or something.

Allow limiting a package to a list of scopes.

Only consider commits from those scopes or no scope for those packages. No scope = all scopes.

Support Python Poetry and npm package.json versions

Allow shortcut aliases for workflows

So instead of doing dobby and then selecting a workflow, you'd do dobby release or similar and it would run the workflow with the alias/shortcut "release".

Refactor version handling code

Currently there's a lot of duplicated code around the version enums just to make sure we end up writing back the correct format / file name. We can probably abstract up a level to have the enum be MetaData or something, separate from the version handling.

Support `cargo-bininstall`

Installing from source is quite slow—supporting cargo-bininstall and making it the recommended install method should be an easy win for speeding up installs.

Fix Windows Artifacts

Right now the release workflow fails when building the Windows artifacts. See https://github.com/knope-dev/knope/actions/runs/2465856749

Setup CD to crates.io

Support GitHub Issues

Make SwitchBranches update files

SwitchBranches right now will properly set the current ref to the branch, but won't actually update the tree. So if you resume work on something, for example, you will still have changes from the previous branch instead of changes from the target branch.

Use mdbook (or similar) for user documentation

`PrepareRelease` should parse all commits from previous non-pre release

Instead of picking the most recent tag, PrepareRelease should look for a tag that was created by Release (do after #212). For the case when moving from a pre-release version to a released version, PrepareRelease should go back to the tag of the last real release when deciding on rules & notes. For the case when moving from prerelease -> prerelease, recalculate the version from the last real release, then compare to the version of the last prerelease to decide if it needs updating.

Some examples, for clarity:

1. Tags v0.1.0 and v0.1.1-rc.0 exist. When running PrepareReleae without a prerelease_label, all commits from v0.1.0 onward should be considered when calculating the next version and generating change notes. This may be v0.1.1 or v0.2.0.
2. Tags v0.1.0 and v0.1.1-rc.0 exist. When running PrepareRelease with a prerelease_label, all commits from v0.1.0 onward should be considered when calculating the next version. If that version is 0.1.1, increment the prerelease label, resulting in 0.1.1-rc.1. If the next version is 0.2.0 (because a breaking change has been added since 0.1.1-rc.0), use 0.2.0-rc.0.

Update monorepo usages after bumping a package

For monorepo support to really work, this also has to go hunt and update co-dependent packages. So whenever a package is updated, Knope should go check every other registered file of the same type for dependencies that match the package name and update them. Lockfiles will probably also need updating—but lockfiles tend to have hashes which could get tricky to do without calling out to the package manager.

Originally posted by @dbanty in #153 (comment)

RUSTSEC-2020-0056: stdweb is unmaintained

stdweb is unmaintained

Details
Status	unmaintained
Package	stdweb
Version	0.4.20
URL	koute/stdweb#403
Date	2020-05-04

The author of the stdweb crate is unresponsive.

Maintained alternatives:

• wasm-bindgen
• js-sys
• web-sys

See advisory page for additional details.

Allow specifying multiple, independent packages.

Change the way that single-package definition works so it looks like this:

[package]
versioned_files = [...]
changelog = ""

For multiple packages, it should look like this:

[[packages]]
versioned_files = [...]
changelog = ""
name = ""  # New required field when defining multiple

The name field will be usable in a few ways:

1. When creating a GitHub release, name it " " to differentiate between releases (with notes) for different packages.
2. The tag of the release should be <name>/v<version> to avoid version tag conflicts. This is the tagging scheme supported by Go modules—as long as name is the same as directory.
3. Useful to include in logging to specify which packages are being updated, especially in dry-runs

The BumpVersion and Release steps will apply to all packages.

Rename the project

Because the current name has bad associations.

Create GitHub Releases

If a GitHub project is configured, create a GitHub release via API when UpdateProjectFromCommits is called.