Make protected-file policy configurable and consistent for migration branches
- Ngôn ngữ chính
- Python
- Star
- 10
- Fork
- 0
- Chỉ số merge pull request
- Không có pull request nào được merge trong 30 ngày
Mô tả
## 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.
Hướng dẫn đóng góp
Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này
Hướng nghiên cứu
Bắt đầu bằng cách xem xét install.md và workflows/crane.md, sau đó xác định các bài kiểm thử installer và workflow prompt được đề cập trong issue. Theo dõi cách hành vi đối với các tệp được bảo vệ được cấu hình cho create-pull-request và push-to-pull-request-branch. Công việc được xem là hoàn tất khi policy được chọn đã được ghi lại, được áp dụng nhất quán và đầu ra fallback không bị coi là một iteration thành công nếu không có commit trên branch.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- github-actions, python
- Lĩnh vực
- devops, tooling
- Loại issue
- Tính năng
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Ít trao đổi
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 35/100