Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
170 lines (125 loc) · 7.62 KB

CONTRIBUTING.md

File metadata and controls

170 lines (125 loc) · 7.62 KB

Contributing

Knope is open to all kinds of contributions—if you want to contribute code there are a few helpful hints.

Docs

The docs website is built using starlight. The source is contained in the docs directory. The easiest way to find a document to edit is to go to that doc on the website and click on "Edit page" at the bottom.

Running locally

npm --prefix docs install, then npm --prefix docs start (or mise run serve-docs).

Docs linting

CI will fail if the docs are not formatted correctly or there are broken relative links. Use mise run reformat to reformat the docs and mise run build-docs to check for broken links.

mise and mise.toml

mise is a polyglot tool version manager and task runner (like make) which makes it easier to run common tasks the same way on many platforms. Specifically, you can run the same sorts of commands that CI does to replicate failures (or prevent them) locally! Start by installing via your favorite method (like curl https://mise.run | sh). Then, run mise tasks to see all the available tasks.

Mise also manages tool versions like Node.js, cargo-deny, taplo, and prettier. When you run mise install, it will install all the tools defined in mise.toml at the specified versions.

Formatting

This project uses rustfmt to format Rust code, but depends on unstable features (for example, sorting imports). You need to install the nightly toolchain (for example, with rustup toolchain install nightly) before formatting the code.

Prettier formats Markdown (via npx) and Taplo formats TOML. mise install will install all required tools including Taplo and Prettier. Node.js/NPM will also be installed by mise.

Snapshot Tests

Most of the tests for Knope are end-to-end snapshot tests in the tests directory, where one directory/module corresponds to one test. To create a new test:

  1. Copy a test directory
  2. Add it as a mod to whatever directory is above it.
  3. Change the contents of in as required for what you're testing.
  4. Change the contents of out to match what in should look like after running the command (for example, increased versions)
  5. Change mod.rs to have the setup & command invocation that you want
  6. Run the test with mise run test (or cargo test)
  7. If the test fails, you can run SNAPSHOTS=overwrite mise run test to update the snapshots

How snapshot tests work

Most snapshot tests look like this:

#[test]
fn name_of_test() {
    TestCase::new(file!())  // Corresponds to a directory you make for this test
        .git(&[              // Run Git commands as needed to set up the test
            Commit("Initial commit"),
            Tag("v0.1.0"),
        ])
        .env("KNOPE_PRERELEASE_LABEL", "alpha")  // Set environment variables as needed
        .run("prepare-release --prerelease-label alpha")  // The command you want to run, omitting the binary name
}

This test must be in a "test directory," which has the following:

  1. An in directory with all the files that the command needs to run. TestCase::run will create a temporary directory, copy the contents of in into it, and run the command from there.
  2. An out directory, if the command should alter the files in in.
  3. If the command should succeed (exit with a 0 status code):
    1. A stdout.log file if the command produces an output.
    2. A dryrun_stdout.log file if .run() should also execute the command with --dry-run to snapshot the output.
  4. If the command should fail (exit with a non-0 status code):
    1. A stderr.log file if the command should fail and produce an error message.
    2. A dryrun_stderr.log file if .run() should also execute the command with --dry-run to snapshot the output.

If neither of stdout.log or stderr.log are present, the command should succeed and produce no output.

TestCase leverages snapbox under the hood, so you can set SNAPSHOTS=overwrite to update the snapshots if you've made changes to the test.

The setup functions (new, git, env) of TestCase are const, so you can define them once and reuse them in multiple cases, when slightly different setups should produce the same results (for example, in tests/prepare_release/override_prerelease_label/mod.rs).

Integration tests

In addition to the snapshot tests, there are integration tests that exercise real HTTP calls against the GitHub and Gitea APIs. These validate that the HTTP client works correctly end-to-end and are not part of the default test suite. You must run them manually if you want to test a change.

Running locally

# Run all integration tests (requires all env vars below)
mise run integration-test

# Run only GitHub tests
mise run integration-test-github

# Run only Gitea tests
mise run integration-test-gitea

Required environment variables

GitHub tests

Variable Description
KNOPE_INTEGRATION_GITHUB_TOKEN Fine-grained personal access token (see below)
KNOPE_INTEGRATION_GITHUB_OWNER Owner (user or org) of the test repository
KNOPE_INTEGRATION_GITHUB_REPO Name of the test repository

Gitea tests

Variable Description
KNOPE_INTEGRATION_GITEA_TOKEN Personal access token for the Gitea instance
KNOPE_INTEGRATION_GITEA_HOST Full URL of the Gitea instance (like https://codeberg.org)
KNOPE_INTEGRATION_GITEA_OWNER Owner (user or org) of the test repository
KNOPE_INTEGRATION_GITEA_REPO Name of the test repository

Setting up test repositories

Each test pushes its own branch and creates a v0.1.0 release from scratch, then cleans everything up at the end. The repositories don't need any content.

GitHub

  1. Create a dedicated test repository under a user or organization (something like knope-dev/knope-integration-tests). It can be public or private. An empty repository (no initial commit) is fine.
  2. Create a fine-grained personal access token scoped to the test repository with the following permissions:
    • Contents: Read and write (for pushing branches, creating tags and releases)
    • Pull requests: Read and write

Gitea (and Codeberg)

  1. Create an account on the Gitea instance you want to test with (for example Codeberg).
  2. Create a dedicated test repository (for example knope-integration-tests). An empty repository is fine.
  3. Create a personal access token in your Gitea account settings with repository read/write permissions.

What the tests do

Each test:

  1. Creates a temporary local git repository pre-configured at version = "0.1.0".
  2. Pushes a test branch (something like integration-test-release) to the remote.
  3. Runs knope release, which calls the GitHub/Gitea API to create a v0.1.0 release and tag on the remote.
  4. Verifies the release exists via the API.
  5. Deletes the release, tag, and branch to leave the repository clean.

If a test fails partway through, the next run will detect and clean up any leftover resources before proceeding.