Skip to content

SI-22: Extract torrust-located-error to a standalone repository #1894

Description

@josecelano

Goal

Move the torrust-located-error crate out of the torrust-tracker workspace into its own standalone repository so that it can be maintained, versioned, and published independently of the tracker.

Background

The torrust-located-error package provides an error decorator that attaches source-location information to errors — a generic debugging utility with no tracker-specific logic. Its only runtime dependency is tracing, a general-purpose structured logging crate. The crate was renamed from torrust-tracker-located-error to torrust-located-error by SI-10 (#1823) which was completed in May 2026. The crate has zero workspace-path dependencies — its only runtime dep (tracing) is an external published crate. Extraction is therefore unblocked. The crate under its new name (torrust-located-error) is not yet published on crates.io. The old name (torrust-tracker-located-error v3.0.0) is published. Publishing torrust-located-error from the standalone repository is part of this issue's scope. This issue is a subissue of EPIC #1669 (Overhaul: Packages).

Scope

In Scope

  • Create a new standalone repository torrust/torrust-located-error in the Torrust GitHub organisation.
  • Move packages/located-error/ to the new repository, preserving git history (using git filter-repo).
  • Make Cargo.toml self-contained (remove workspace inheritance).
  • Verify the standalone repository builds and tests pass independently.
  • Set up CI in the new repository (mirror the relevant CI workflows from the tracker repo).
  • Publish torrust-located-error on crates.io from the new standalone repository.
  • Update all 5 workspace consumers (see list below) to reference torrust-located-error as a crates.io version dependency instead of a path dependency.
  • Remove the path-based dep registration from root Cargo.toml if present.
  • Remove packages/located-error from the workspace if listed.
  • Delete the packages/located-error/ directory from the tracker repository.
  • Update prose references in packages/AGENTS.md, AGENTS.md, and docs/packages.md (move torrust-located-error to the "Extracted" section).
  • Yank the old torrust-tracker-located-error crate on crates.io after workspace consumers have been migrated.

Out of Scope

  • Changes to the crate's API or behaviour.
  • Updating downstream repositories outside the Torrust organisation.

Workspace consumers to migrate

The following 5 files must have their torrust-located-error dep changed from a path dep to a crates.io version dep:

  • packages/configuration/Cargo.toml
  • packages/http-protocol/Cargo.toml
  • packages/axum-server/Cargo.toml
  • packages/tracker-core/Cargo.toml
  • packages/tracker-client/Cargo.toml

Implementation Plan

Status values: TODO, IN_PROGRESS, BLOCKED, DONE.

ID Status Task Notes / Expected Output
T1 DONE Verify crate has no workspace path dependencies packages/located-error/Cargo.toml lists only external crates (tracing), plus thiserror as dev-dep
T2 DONE Create standalone repository torrust/torrust-located-error Repo created at https://github.com/torrust/torrust-located-error - initialised with no commits on main
T3 TODO Move packages/located-error/ to the new repository (preserving git history) New repo contains full history for packages/located-error/
T4 TODO Make Cargo.toml self-contained (remove workspace inheritance; pin explicit values) All fields explicit; no workspace = true entries
T5 TODO Verify standalone repository: cargo build and cargo test pass with no path deps Clean build and tests pass; no path deps remain
T6 TODO Set up CI in the new repository CI workflow with linter all + cargo test
T7 TODO Publish torrust-located-error on crates.io from the standalone repository Published v0.1.0 (or appropriate initial version); crates.io page exists
T8 TODO Update all 5 workspace consumers (see list above): path dep -> crates.io version dep torrust-located-error = "0.1.0" in all 5 files; no path deps remain
T9 TODO Remove packages/located-error entry from workspace if listed Verify root Cargo.toml [workspace] members list; remove if present
T10 TODO Delete packages/located-error/ directory from the tracker repository Directory removed via git rm -r
T11 TODO Update packages/AGENTS.md, AGENTS.md, docs/packages.md torrust-located-error moved to an "Extracted packages" section
T12 TODO Yank old torrust-tracker-located-error from crates.io (optional, after downstream migrated) cargo yank torrust-tracker-located-error@3.0.0
T13 TODO Run cargo build --workspace and cargo test --workspace Clean build and all tests pass
T14 TODO Run linter all Exit code 0
T15 TODO Update EPIC #1669 tables Package inventory and desired state tables updated; subissue row set to DONE

Verification Plan

Automatic Checks

  • cargo build --workspace
  • cargo test --doc --workspace
  • cargo test --tests --workspace --all-targets --all-features
  • linter all
  • cargo machete (no unused dependencies)

Manual Verification Scenarios

ID Scenario Steps Expected Result
M1 No path dep on torrust-located-error remains in workspace grep -r "path.*packages/located-error" . --include="*.toml" Zero matches
M2 packages/located-error/ directory is gone ls packages/located-error No such file or directory
M3 Standalone repo builds and tests pass independently In new repo: cargo build && cargo test --workspace Clean build; all tests pass
M4 New crate visible on crates.io Visit https://crates.io/crates/torrust-located-error Crate page exists
M5 torrust-located-error CI green in new repository Check GitHub Actions on torrust/torrust-located-error All workflows green

Metadata

Metadata

Assignees

Labels

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions