v0.2.0

Prose

ritual 0.2.0 makes the everyday management of a project's tasks commands rather than manual edits. create makes a task, inside a project or outside one; import brings in someone else's; remove takes one out in the order the build needs; and migrate moves a 0.1 project into the new layout, where every ritual lives in .rituals/. It also changes how a refusal reports its causes and lets it choose its exit status, which is a breaking change for task code that formats a Failure itself. Every ritual crate releases together at 0.2.0, with three new ones: rituals-core-import, rituals-core-remove and rituals-core-migrate.

Breaking changes

Tasks live in .rituals/, and cargo ritual migrate moves them. A project's own tasks now go in .rituals/<name> instead of tasks/<name>, whoever they are for. A 0.1 project keeps building and running as it is until you move it. To upgrade:

1. Set rituals under [workspace.dependencies] in the workspace's Cargo.toml, and rituals-core in the CLI crate's Cargo.toml (ritual = { package = "rituals-core", ... }), to 0.2.0. Both: tasks built on rituals 0.1 do not fit a bundle built on 0.2, and the command line will not compile until both match.
2. Run cargo build, so Cargo.lock follows, and commit everything.
3. Run cargo ritual migrate. It needs a git work tree with nothing uncommitted.
4. Review the changes with git status and git diff, and commit them.

migrate moves every task under tasks/, repoints every manifest path that crosses into or out of a moved directory, keeps a members glob as a glob, and lists (without editing) any other file in the repository that still mentions tasks/, such as a CI workflow. Run again, it says nothing to migrate. It never writes publish, so Cargo reads each moved task exactly as before. Subdirectories of .rituals/ are yours to arrange: ritual reads no meaning into their names. A .rituals/* glob in members also matches a grouping directory with no manifest, and Cargo then refuses the workspace, so give that directory an exclude entry or list the members explicitly.

add is deprecated in favour of create, and will be removed in ritual 0.3.0. add still works in 0.2.0. It prints add is now create, and will be removed in ritual 0.3.0 on standard error, then does exactly what create does. Use create in its place.

A ritual made by create, or by add, is private by default. It writes publish = false into the new task's manifest unless you pass --public, which 0.1's add and create never wrote. Pass --public for a ritual you mean to publish, or remove the key from its manifest later. Rituals that already exist are not touched.

A Failure's Display is its message alone. Its cause is only its source(). The refusal line dispatch prints still names every cause, now all the way down the chain, each once. Code that formats a Failure itself, with to_string() or format!("{failure}"), and wants the causes, uses failure.with_causes(). A cause whose own Display already includes its source, such as a thiserror variant with {0} in its message and #[from] on the field, now shows that source twice in the refusal line where 0.1 showed it once: build the refusal with Failure::new(error.to_string()) in place of caused_by, or take the source out of the error's message.

CommandLine::from_dispatch takes the command path as a third argument, and panics on an empty one. It is the hidden constructor a task crate's unit tests use to stand in for dispatch. Pass the subcommand names the task would be reached by, top first, such as ["lint"].

Task::group panics on a child key that Name::new refuses: one with an uppercase letter, an underscore, a space, or any other spelling a project's own key for a task couldn't have, and crate, self or super. The panic comes at construction, in both build profiles, and names the key and the reason. Rename the child, for example db_sync to db-sync.

rituals-compose: rollback::attempt takes a Wording in place of a retry string. Use Wording::project(root, retry) for a run that changes a project that was already there, or Wording::fresh_directory(current_dir, dir, retry) for one that makes a directory from nothing. Project::declares_dependency_key keeps its signature but now treats - and _ as one name, as Rust does. layout::tasks_directory is now rituals_directory, and source::assert_is_a_ritual_checkout is now ensure_a_ritual_checkout. manifest::declares_a_workspace, rust_name::extern_identifier, Manifest::path_dependency_directories (with ManifestRole) and Metadata::ensure_runs_in_its_own_project are no longer public. The test-util feature is this repository's own test support, outside the crate's stability promise.

New

• cargo ritual create works inside a project and outside one. In its own project it scaffolds the task into .rituals/<name>, adds it to the workspace's members and to the command line's dependencies and task list, and regenerates. It also takes a path below .rituals/ (create .rituals/private/lint from the root, or create private/lint from inside .rituals/), read from the current directory the way a shell reads it. Outside a project, where a crate made there would build on its own, it makes a stand-alone crate in the current directory and ends with the cargo ritual import … --path … line to run in the project that will use it. Anywhere else it refuses before writing anything and says what to do instead. --path and --git are for outside a project, and are refused inside one.

• cargo ritual import brings in someone else's task in one command: it adds the dependency with cargo add, checks the crate is a task built on the same rituals as the project, appends its key to the task list and regenerates. Registry, git and path sources all work:

  cargo ritual import acme-linting@1.2.0 lint
  cargo ritual import acme-linting lint --git https://github.com/acme/rituals --tag v1.2.0
  cargo ritual import lint --path ../lint

  A refused or failed import puts the CLI's manifest and Cargo.lock back byte for byte.

• cargo ritual remove <key | crate> takes a task out in the order the build needs: out of the task list, regenerated, then the dependency and, for a task that is a workspace member, its members entry. A failure anywhere in that puts every file back. Only then is a member's directory deleted, and only if git can give back every file in it. A path dependency outside the workspace loses its dependency line and nothing else.

• cargo ritual migrate, described above. It runs every layout migration that applies, oldest first, and stores nothing between runs.

• A task can learn the command it was run under. A task built with Task::receiving_command_line reads the path it was invoked under with CommandLine::command_path(), such as ["tools", "db", "sync"], and the command to run it again with CommandLine::cargo_command(), such as cargo ritual tools db sync. cargo_command() holds in a project made by new; command_path() holds everywhere.

• A refusal can choose its exit status. Failure::new(…).exiting_with(status), with status a RefusalStatus of 1, 3 to 100, or 102 to 125. RefusalStatus::new is const and refuses 0, 2, 101, and 126 and above, since each already means something to whoever ran the command. Failure::status reads it back. A plain Failure still exits 1, and the refusal line doesn't change with the status.

• rituals::warn writes a line a person should heed that isn't the run's result to standard error.

Fixed

• ritual's own hints, such as "run cargo ritual regenerate", go through the key a project mounted ritual's bundle under. Before, a project that remounted the bundle got hints naming ritual that didn't run.
• import, remove and migrate name their own re-run through the key they were mounted under, including when one of them is mounted on its own.
• When import, remove, migrate or create can't put something back after a failure, the command it says to run again is the whole command, cargo ritual import greeter rather than import greeter, so it can be pasted.
• A refused add no longer leaves a Cargo.lock it created or rewrote: the run is recorded from its first cargo metadata on, and a regenerate that fails puts the project back too. Every command that promises a rollback now records the lockfile before Cargo can touch it, including one committed out of Cargo's own layout.
• A rollback no longer claims to have put the project back when it put nothing back. When some changes couldn't be put back, it names them and says to check them before retrying.
• In a project whose CLI crate is the workspace root, add dropped the members entry it had just written and printed updated Cargo.toml twice. create writes that manifest once.
• add std (or core) is refused, since a key that hides Rust's own crate breaks the generated file. alloc, test and proc-macro still work as keys.
• A key that differs from an existing dependency only by - and _ is refused by add, since Rust reads both as one name.
• add reads an inline metadata = { ritual = { tasks = [] } }, which it used to refuse.
• A task's --help shows only the description it was declared with, not its argument struct's doc comment.

---

What's Changed

• feat(remove): take a task out in the safe order by @freyavanadis in #22
• feat(import): bring a task in from anywhere by @freyavanadis in #28
• docs(compose): drop a doctest's Windows workaround by @freyavanadis in h...

v0.1.2

Prose

This release is a small update to the internal-ish rituals-compose crate to push some functionality into a shared space in preparation for v0.2.0

---

What's Changed

• refactor(compose): share add's rollback by @freyavanadis in #19

New Contributors

• @freyavanadis made their first contribution in #19

Full Changelog: v0.1.1...v0.1.2

Contributors

Everyone who authored or co-authored a commit since v0.1.1:

• @beeauvin
• @delphimoon
• @freyavanadis

v0.1.1

Prose

Maintenance release that changes nothing about the code itself. Primarily targeted at validating our release workflow. So far so good. ^^

What's Changed

• fix(ci): msrv tests flaking on linux due to copied binary by @beeauvin in #1
• ci: release workflows, from a version-bump PR to crates.io by @beeauvin in #2

New Contributors

• @beeauvin made their first contribution in #1
• @github-actions[bot] made their first contribution in #3

Full Changelog: v0.1.0...v0.1.1

Contributors

Everyone who authored or co-authored a commit since v0.1.0:

• @beeauvin
• @delphimoon

v0.1.0

Prose

First public release of rituals. Exciting times. ^^

Full Changelog: https://github.com/hexlace/ritual/commits/v0.1.0