[Feature]: Move bug workflow artifacts to a configurable docs/speckit/bugs root through staged migration

Ouverte
  • Quelque chose ne va pas ?
#5,038 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
30/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Active
Stack technique
github, python
Domaine
developer-experience, tooling

Piste de recherche

Start with extensions/bug/README.md and trace how the assess, fix, and test stages select BUG_DIR, read and write reports, and check prerequisites. The issue calls for coordinated changes across extension instructions, configuration, migration, hooks, documentation, and tests; first map those entry points and existing configuration conventions. Done means the staged rollout and acceptance criteria are covered, including legacy compatibility, custom roots, migration conflicts, and workflow continuity.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

triage-out-of-scope

Problem and rationale

The bundled bug extension stores authored bug reports under .specify/bugs/<slug>/, mixing workflow evidence with tooling/configuration.

Align with github/spec-kit#5037 (https://github.com/github/spec-kit/issues/5037): keep tooling/configuration in .specify/ and authored workflow artifacts under a clearly owned documentation hierarchy. Bug artifacts remain distinct from SDD and idea-assessment artifacts. Parallel assessment tracking: github/spec-kit#5039 (https://github.com/github/spec-kit/issues/5039).

Proposed solution

Introduce explicit opt-in to a configurable bug artifact root, defaulting in the new layout to:

docs/speckit/bugs/<slug>/
  assessment.md
  fix.md
  test.md

The bug extension owns selection and migration; core must not acquire bug-specific knowledge merely to enforce a directory convention. Support an environment root override, provisionally SPECIFY_BUGS_DIR, subject to existing configuration conventions. Define project-level layout selection and environment/project/default precedence so absent environment variables do not redirect ongoing workflows. Do not automatically persist transient overrides. Relative roots resolve against the Spec Kit project root.

Apply one resolved root consistently across assess/fix/test, slug uniqueness, prerequisites, reads/writes, hook context (BUG_DIR), and completion/handoff references. Preserve recorded paths and ongoing workflow selection rather than silently rebasing them under changed configuration.

Migration is explicit and preserves authored content. Competing copies of the same slug must cause an actionable conflict, not arbitrary selection, merging, overwriting, or duplicate workflows. Preserve existing stage semantics, source-editing restrictions, overwrite confirmation, and applicable path-safety guarantees.

Four-stage rollout

  1. Opt-in: Support unified/custom roots while retaining .specify/bugs/ defaults for non-opted-in projects.
  2. Deprecation warnings: Warn on the legacy root with actionable migration guidance, without moving files or changing behavior.
  3. Default flip with legacy opt-out: Default new adoption to docs/speckit/bugs/; preserve explicit legacy compatibility for existing projects and in-progress bugs.
  4. Removal: Retire legacy-root support after an adequate announced transition period. Detect unmigrated workflows and provide migration errors rather than missing-report errors or duplicate artifact creation.

Do not assign specific release versions. Consecutive PRs are not a compatibility window; allow release/adoption time. The extension can progress independently of core and assessment rollouts.

Acceptance criteria

  • Initial opt-in preserves legacy defaults unless explicitly selected.
  • Opted-in defaults use docs/speckit/bugs/<slug>/; an environment override can relocate the root.
  • Selection, persistence, precedence, existing-project detection, and project-relative path resolution are explicit across commands.
  • Invalid configuration produces actionable errors rather than silent fallback.
  • Assess/fix/test, prerequisites, slug collision checks, hooks, and report references use the same selected root.
  • Existing reports, recorded paths, and in-progress stage selection remain coherent across upgrades/configuration changes.
  • Migration is explicit and preserves content; duplicate slugs across roots are surfaced without silent precedence or overwrites.
  • Existing stage semantics, source-code editing restrictions, overwrite protection, and applicable path-safety guarantees remain intact.
  • Warnings do not change behavior; default flip retains documented legacy opt-out; removal reports clear migration errors.
  • Positive and negative coverage demonstrates legacy compatibility, opt-in/custom roots, absent overrides, invalid roots, collisions, and workflow continuity.
  • Extension instructions, documentation, examples, hook guidance, and directly related references are updated together.
  • The staged transition allows adequate announced adoption time without committing to specific versions.

Alternatives and scope

Keeping .specify/bugs/ avoids migration but leaves authored evidence mixed with tooling. Implementing extension paths in core or adding a shared parent-directory variable introduces unnecessary coupling. Environment-only selection and automatic moves risk broken ongoing work and duplicates.

This is a separate tracking issue, not an expansion of the core SDD implementation or an all-stages PR. The existing contract is documented in extensions/bug/README.md, including the three artifact names and hook reuse of BUG_DIR. All agents are affected.

Replaces the mistakenly filed fork issue https://github.com/mnriem/spec-kit/issues/59, with the user's authorization.

AI disclosure

Drafted and filed on behalf of @mnriem using GitHub Copilot App, powered by GPT-6.1 Sol (gpt-6.1-sol), in human-supervised interactive mode. The agent inspected the bundled README and drafted the rationale, rollout, and acceptance criteria from the user-approved discussion. The user authorized upstream filing. Reasoning-effort setting was not available to report. No implementation changes were made.

Langage dominant
Python
Étoiles
149k
Forks
13.4k
Merge moyen
1 j 5 h
PR mergées (30 j)
223

Préparer son environnement

Ouvrir dans Codespaces

Lance le conteneur de développement du projet dans votre navigateur, avec votre propre compte GitHub.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de github/spec-kit

Toutes les issues de github/spec-kit

Issues similaires

Plus d'issues Python

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.