Make protected-file policy configurable and consistent for migration branches
- Lenguaje dominante
- Python
- Estrellas
- 10
- Forks
- 0
- Métricas de merge de PR
- Sin PR fusionados en 30 d
Descripción
## Background
During the githubnext/apm Python-to-Go migration, Crane repeatedly needed to touch files that are commonly protected: `go.mod`, `go.sum`, workflow files, and other project configuration. With protected files set to `fallback-to-issue`, Crane could describe work in an issue but not push the actual migration commit. That caused false progress and stalled PR updates.
APM locally changed the Crane workflow so `create-pull-request` uses `protected-files: allowed`. The upstream lesson is broader: code migration frequently requires manifest, lockfile, or workflow changes, so protected-file behavior must be explicit, configurable, and consistent across both creating the PR and pushing later iteration commits.
## Problem
The default upstream Crane workflow has `create-pull-request` protected files set to `fallback-to-issue`, while `push-to-pull-request-branch` also has its own protected-file behavior from safe outputs. This can create surprising behavior:
- First accepted iteration can fail to create a useful PR if protected files are touched.
- Later iterations can fail to push to the existing migration branch.
- Crane may write fallback issues that look like progress but do not update the PR branch.
- Migrations involving Go, Node, Python, Java, or Rust often need dependency manifest and lockfile edits.
For a migration tool, touching manifest and lock files is often not exceptional. It is part of the migration.
## Proposed implementation
Make protected-file policy an explicit Crane installation or workflow configuration choice.
Possible design:
1. Add an installer prompt in `install.md`:
- Strict: protected files fall back to issue for maximum safety.
- Migration-friendly: protected files are allowed on Crane migration branches.
- Custom: user provides an allowlist or policy.
2. Apply the selected policy consistently to both:
- `create-pull-request`
- `push-to-pull-request-branch`
3. Document when to use each mode:
- Use strict for repositories where agents must never touch manifests or workflow files without human intervention.
- Use migration-friendly when the migration target requires dependency, lockfile, build, or workflow updates.
4. If a protected-file fallback still happens, Crane should treat it as blocked or incomplete, not as an accepted migration iteration. It should tell the maintainer what policy or allowlist needs to change.
5. Consider per-migration override support in migration frontmatter, for example:
```yaml
protected-files-policy: allowed
```
or
```yaml
protected-files-policy: fallback-to-issue
```
## Suggested test coverage
- Prompt or installer tests that verify the protected-file policy is described.
- Workflow prompt test that verifies the policy applies to both PR creation and PR branch pushes.
- If implemented in installer code, test that the selected policy is written into `workflows/crane.md` before `gh aw compile`.
## Acceptance criteria
- A repository owner can choose strict or migration-friendly protected-file behavior during installation.
- The chosen behavior is applied consistently for initial PR creation and later PR updates.
- Crane does not mark protected-file fallback output as a successful accepted iteration unless a commit actually reached the migration branch.
- Documentation explains why migrations may need to touch manifest and lock files.
## Provenance
This came from githubnext/apm, where the Python-to-Go migration needed dependency and workflow changes and protected-file fallback prevented Crane from generating new PR commits.
Guía de contribución
No hay ninguna guía de contribución indexada para este repositorio
Línea de trabajo
Comienza revisando install.md y workflows/crane.md; después, localiza las pruebas del instalador y de los prompts del workflow mencionadas en el issue. Traza cómo se configura el comportamiento de los archivos protegidos para create-pull-request y push-to-pull-request-branch. Se considera terminado cuando la política seleccionada está documentada y se aplica de forma coherente, y la salida de fallback no se trata como una iteración exitosa sin un commit en la rama.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- github-actions, python
- Área
- devops, tooling
- Tipo de issue
- Nueva funcionalidad
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Estado de actividad
- Tranquilo
- Claridad
- Bastante claro
- Aptitud para principiantes
- 35/100