githubnext / githubnext/crane

Make protected-file policy configurable and consistent for migration branches

Abierto
#7 0 comentarios 0 reacciones 0 asignados Ver en GitHub
enhancement
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

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.