Expose Crane run cadence as an installer choice and tuning guide
- 主要言語
- Python
- スター
- 10
- フォーク
- 0
- PR マージ指標
- 30日以内にマージされた PR はありません
説明
## Background
The githubnext/apm migration needed faster iteration than the default Crane cadence. APM locally changed the Crane workflow schedule from `every 6h` to `every 20m` so Crane could converge in hours rather than days while maintainers were actively watching.
That should not necessarily become the upstream default. It should become an explicit installation and tuning choice.
## Problem
The upstream Crane workflow defaults to a fixed schedule. The README explains that users can tune cadence, and `install.md` asks about migration frequency, but the installed workflow still needs a clear path for applying and documenting the chosen cadence.
Different migrations need different cadences:
- Active, high-attention migration: every 20m or every 1h.
- Normal migration in a busy repository: every 6h.
- Low-risk background migration: daily or weekly.
- Multiple active migrations: cadence interacts with the scheduler because each run selects only one migration.
If the cadence is too slow, Crane appears idle and migrations take too long. If it is too fast, maintainers get too many commits and CI runs.
## Proposed implementation
Update Crane installation and documentation so cadence is a first-class choice.
Implementation options:
1. In `install.md`, keep the frequency prompt but make the follow-through explicit:
- The agent should edit `workflows/crane.md` to set `on.schedule` to the selected cadence.
- Then it should run `gh aw compile crane`.
2. In `README.md`, add a cadence tuning section with examples:
```yaml
on:
schedule: every 20m
```
```yaml
on:
schedule: every 1h
```
```yaml
on:
schedule: every 6h
```
3. Explain trade-offs:
- Faster cadence gets feedback quickly but increases CI usage and review pressure.
- Slower cadence is calmer but may make migrations look stalled.
- For multiple migrations, faster workflow cadence may still run only one selected migration per trigger.
4. Consider adding guidance to `create-migration.md` for per-migration `schedule:` frontmatter versus workflow-level cadence. Users should understand both knobs:
- Workflow cadence: how often Crane wakes up.
- Migration schedule: whether a specific migration is due when Crane wakes up.
## Suggested test coverage
- Documentation test or prompt test that asserts `install.md` says to update `workflows/crane.md` and compile after selecting cadence.
- If installer automation exists, test that the selected cadence changes the workflow source before compilation.
## Acceptance criteria
- A new Crane installer run asks for cadence and applies it to the workflow source.
- Documentation explains recommended cadence ranges and trade-offs.
- Documentation distinguishes workflow wake-up cadence from per-migration schedule frontmatter.
- Users can reproduce the APM-style fast loop intentionally without hand-editing undocumented workflow internals.
## Provenance
This came from githubnext/apm, where changing Crane to `every 20m` helped the Python-to-Go migration converge much faster while humans were actively reviewing.
コントリビューションガイド
このリポジトリのコントリビューションガイドは索引されていません
調査の方向性
install.mdから始めて、cadence promptがどのように処理されるかを追跡し、その後 workflows/crane.md と gh aw compile のステップを確認します。README.md と create-migration.md で必要となる cadence のガイダンスを、workflow cadence と migration schedule frontmatter の違いも含めて比較します。選択した cadence がコンパイル前に適用され、トレードオフが文書化され、関連するドキュメントまたはプロンプトのテストが成功すれば完了です。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- github-actions
- 領域
- devops, documentation
- issue の種類
- 機能追加
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 活発さ
- 静か
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 58/100