Skip to content

Rename torrust-tracker-located-error to torrust-located-error #1823

Description

@josecelano

Goal

Rename the Cargo crate torrust-tracker-located-error to torrust-located-error to reflect
that it is a generic, tracker-independent error decoration utility that can be used in any
Rust project (e.g., torrust-index).

Background

The located-error package (packages/located-error) 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. There is nothing in the
implementation that ties it to the BitTorrent tracker.

The torrust-tracker- prefix implies a tracker-only scope that does not reflect the crate's
actual purpose. The rename:

  • Makes the crate identity match its scope.
  • Signals to downstream users that it is reusable outside the tracker.
  • Prepares it for potential extraction to a standalone repository in a future cycle.

The current crate name torrust-tracker-located-error is published on crates.io. The
rename requires publishing the new name torrust-located-error and handling the old
published name (deprecation notice, then yank after downstream migration).

Pre-implementation review: There is an open question on whether this package should be
kept and renamed, or removed entirely. A keep-vs-delete analysis is recorded in the local
spec and will be reviewed in the draft PR before implementation starts.

This issue is a subissue of EPIC #1669 (Overhaul: Packages) — SI-10.

Scope

In Scope

  • Rename the name field in packages/located-error/Cargo.toml.
  • Update all Cargo.toml files in the workspace that reference
    torrust-tracker-located-error.
  • Update all Rust source files using torrust_tracker_located_error:: to
    torrust_located_error::.
  • Update prose in packages/AGENTS.md, AGENTS.md, docs/packages.md, and
    packages/located-error/README.md.
  • Update .github/workflows/deployment.yaml, docs/release_process.md, and the relevant
    skills under .github/skills/ that reference the crate name.
  • Verify the workspace builds and all tests pass.
  • Publish torrust-located-error on crates.io.
  • Handle the old crates.io name torrust-tracker-located-error: deprecation notice first;
    yank after downstream Torrust repositories are migrated.

Out of Scope

  • Moving the crate to a separate repository (a future extraction subissue).
  • Changes to the crate's API or behaviour.

Implementation Plan

ID Task
T1 Rename name in packages/located-error/Cargo.toml
T2 Update root Cargo.toml workspace dependency key
T3 Update all 5 dependent package Cargo.toml files
T4 Update Rust source use / path references
T5 Update prose in packages/AGENTS.md, AGENTS.md, docs/packages.md, package README.md
T6 Update .github/workflows/deployment.yaml, docs/release_process.md, related .github/skills/
T7 Run cargo build --workspace and cargo test --workspace
T8 Run linter all
T9 Publish torrust-located-error on crates.io
T10 Add deprecation notice to torrust-tracker-located-error on crates.io
T11 Migrate downstream Torrust repositories (e.g., torrust-index)
T12 Yank all versions of torrust-tracker-located-error on crates.io
T13 Update EPIC #1669 Package Inventory and Desired Package State tables

Dependent packages for T3 (5 files):

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

Acceptance Criteria

  • packages/located-error/Cargo.toml declares name = "torrust-located-error".
  • No Cargo.toml file in the workspace references torrust-tracker-located-error.
  • No Rust source file uses torrust_tracker_located_error::.
  • cargo build --workspace succeeds with zero errors.
  • cargo test --workspace passes with zero failures.
  • linter all exits with code 0.
  • torrust-located-error is published and visible on crates.io.
  • torrust-tracker-located-error has a deprecation notice pointing to the new name.
  • Downstream Torrust repositories have been migrated.
  • torrust-tracker-located-error is yanked on crates.io (only after downstream migration).
  • EPIC Overhaul: Packages #1669 Desired Package State table lists torrust-located-error.

Local Spec

Spec lives in the local repository and will be moved to
docs/issues/open/<issue-number>-1669-10-rename-torrust-tracker-located-error-to-torrust-located-error.md
once this issue is opened.

Related to #1669

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions