docToolchain / docToolchain/docToolchain

Monkey-patching: override installed tasks from the project (v4)

Open
#1,668 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Groovy
Stars
864
Forks
240
Avg merge
2m
Merged PRs (30d)
2

Description

Part of #1666. **MoSCoW: Must.**

## User Story

> As a **build/tooling maintainer**, I want to copy an installed task into my project and modify it, so that `dtcw` runs my version instead of the shipped one — for this project only, committed with the docs.

Implements **UC-CT-2** and goal **G-2** of the spec (`src/docs/arc42/spec/02_project_local_tasks.adoc`).

## Scope

- A project script whose name matches an installed task **overrides** it (project-first resolution, BR-3).
- Every override run prints a visible `Note:` to stderr; `./dtcw tasks` flags the task as `overridden by …` (BR-4, goal G-3).
- `copyTask ` copies an installed script into the project for editing; refuses to overwrite an existing copy.
- The copied script keeps working: `dtcw` passes `-Ddtc.scriptsHome` so `lib/` helpers and bundled resources resolve from the installation (BR-6). This is **ADR-17**, the enabler for the whole EPIC — without it a copied script fails to load its helpers.

## Acceptance Criteria (Gherkin — see spec)

- A same-named project script shadows the installed task; `./dtcw ` runs the project copy, not the installed one (BR-3).
- `./dtcw ` prints an override note (BR-4).
- `./dtcw tasks` shows the task as overridden (BR-4).
- `copyTask` refuses to overwrite an existing project copy (EARS-6).
- Deleting the project copy falls back to the installed task (no note).

## Definition of Done

- Implemented in Bash `dtcw` (resolution + `dtc.scriptsHome`) + `scripts/copyTask.groovy`.
- `scriptDir`/`dtcHome` idiom updated across v4 scripts that load `lib/` (ADR-17).
- `test/custom_tasks.bats` covers override run, override listing.
- Documented: `015_tasks/03_task_copyTask.adoc` + manual `45_custom_tasks.adoc`.
- ADR-16 / ADR-17 recorded.

Contributor guide

Open the contributing guide

Research direction

Start with the Bash dtcw entry point and scripts/copyTask.groovy, then review the v4 scripts that load lib/ and the ADR-17 requirement. Run test/custom_tasks.bats while checking the listed acceptance criteria; done includes the task override and fallback behavior, copyTask refusal, documentation updates, and ADR-16/ADR-17 records.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, groovy
Domain
cli, documentation, testing, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.