docs: add merge checklist and xlsx decision
This commit is contained in:
@@ -1,37 +1,21 @@
|
|||||||
# Change Summary for Commit / PR
|
# PR Summary
|
||||||
|
|
||||||
## Suggested commit title
|
## Title
|
||||||
|
|
||||||
`fix: gitea seed recovery and workflow checkout ref`
|
|
||||||
|
|
||||||
## Suggested PR title
|
|
||||||
|
|
||||||
`Synology KIS workflow recovery, branch checkout fix, and seed JSON tracking`
|
`Synology KIS workflow recovery, branch checkout fix, and seed JSON tracking`
|
||||||
|
|
||||||
## What changed
|
## Short Body
|
||||||
|
|
||||||
- Updated `.gitea/workflows/kis_data_collection.yml` to checkout the triggering ref instead of always fetching `main`.
|
- `kis_data_collection.yml` now checks out the triggering ref instead of always fetching `main`.
|
||||||
- Added a `Prepare Raw Seed Snapshot` step that accepts `GatherTradingData.json`, regenerates it from `GatherTradingData.xlsx`, or downloads the workbook from Google Drive when `.clasprc.json` is available.
|
- `Prepare Raw Seed Snapshot` now accepts `GatherTradingData.json`, regenerates from `GatherTradingData.xlsx`, or falls back to Google Drive download via `.clasprc.json`.
|
||||||
- Switched KIS credential guards to explicit shell checks with clearer error messages.
|
- `qualitative_sell_strategy.yml` uses the same checkout and seed-recovery path.
|
||||||
- Applied the same checkout and seed-recovery logic to `.gitea/workflows/qualitative_sell_strategy.yml`.
|
- `GatherTradingData.json` is now tracked in git so the runner gets a canonical seed snapshot.
|
||||||
- Tracked `GatherTradingData.json` in git so the runner always receives a canonical seed snapshot.
|
- `tools/validate_platform_transition_wbs_v1.py` was updated to validate the new workflow text without false positives.
|
||||||
- Updated `tools/validate_platform_transition_wbs_v1.py` to validate the new workflow structure without false positives from shell guards.
|
|
||||||
- Expanded the Gitea variables runbook and failure analysis docs with the new recovery path and Google Drive fallback.
|
|
||||||
|
|
||||||
## Evidence to cite in the PR
|
## Verified
|
||||||
|
|
||||||
- `python tools/validate_platform_transition_wbs_v1.py`
|
- `python tools/validate_platform_transition_wbs_v1.py`
|
||||||
- `python tools/validate_gitea_secrets_contract_v1.py`
|
- `python tools/validate_gitea_secrets_contract_v1.py`
|
||||||
- `python tools/validate_gitea_token_home_v1.py --dispatch --workflow kis_data_collection.yml --ref codex/roadmap-publish`
|
- Gitea run `165` on `kis_data_collection.yml` succeeded
|
||||||
- `python tools/validate_gitea_token_home_v1.py --dispatch --workflow qualitative_sell_strategy.yml --ref codex/roadmap-publish`
|
- Gitea run `166` on `qualitative_sell_strategy.yml` succeeded
|
||||||
|
|
||||||
## Verified runtime result
|
|
||||||
|
|
||||||
- `run 165` on `kis_data_collection.yml` succeeded after the checkout-ref and seed changes.
|
|
||||||
- `Prepare Raw Seed Snapshot` passed with the tracked `GatherTradingData.json`.
|
|
||||||
- The KIS collector wrote SQLite output and the run completed successfully.
|
|
||||||
|
|
||||||
## Seed file decision
|
|
||||||
|
|
||||||
- `GatherTradingData.json`: track in git.
|
|
||||||
- `GatherTradingData.xlsx`: keep untracked and ignored unless a future workflow explicitly needs the workbook in the repo checkout. The current workflow can regenerate or download the workbook when needed.
|
|
||||||
|
|||||||
@@ -0,0 +1,35 @@
|
|||||||
|
# GatherTradingData.xlsx Decision
|
||||||
|
|
||||||
|
## Option A: Track `GatherTradingData.xlsx`
|
||||||
|
|
||||||
|
Pros:
|
||||||
|
|
||||||
|
- Runner checkout always has the workbook.
|
||||||
|
- JSON regeneration never depends on Google Drive access.
|
||||||
|
- Manual recovery is simpler for operators.
|
||||||
|
|
||||||
|
Cons:
|
||||||
|
|
||||||
|
- Large binary file increases repo size and diff noise.
|
||||||
|
- Workbook changes become harder to review.
|
||||||
|
- The repository becomes dependent on spreadsheet artifacts that are not needed for normal runtime collection.
|
||||||
|
|
||||||
|
## Option B: Keep `GatherTradingData.xlsx` untracked
|
||||||
|
|
||||||
|
Pros:
|
||||||
|
|
||||||
|
- Repository stays smaller and cleaner.
|
||||||
|
- `GatherTradingData.json` remains the canonical runtime seed.
|
||||||
|
- Workflow can regenerate from local workbook or download it only when required.
|
||||||
|
|
||||||
|
Cons:
|
||||||
|
|
||||||
|
- If both seed files are missing, the workflow needs a download fallback or an operator intervention.
|
||||||
|
- Recovery depends on `.clasprc.json` or another source of truth.
|
||||||
|
|
||||||
|
## Recommendation
|
||||||
|
|
||||||
|
- Keep `GatherTradingData.xlsx` untracked.
|
||||||
|
- Track `GatherTradingData.json` in git.
|
||||||
|
- Preserve the workflow fallback path for regeneration and download.
|
||||||
|
|
||||||
@@ -0,0 +1,25 @@
|
|||||||
|
# Main Merge Final Checklist
|
||||||
|
|
||||||
|
## Before merge
|
||||||
|
|
||||||
|
- Confirm PR `#67` is the active review target.
|
||||||
|
- Confirm both workflow dispatch smoke tests succeeded:
|
||||||
|
- `kis_data_collection.yml`
|
||||||
|
- `qualitative_sell_strategy.yml`
|
||||||
|
- Confirm `python tools/validate_platform_transition_wbs_v1.py` passes.
|
||||||
|
- Confirm `python tools/validate_gitea_secrets_contract_v1.py` passes.
|
||||||
|
- Confirm `GatherTradingData.json` is present in the branch.
|
||||||
|
|
||||||
|
## Merge criteria
|
||||||
|
|
||||||
|
- `Checkout Code` uses the triggering branch ref.
|
||||||
|
- `Prepare Raw Seed Snapshot` succeeds without manual intervention.
|
||||||
|
- KIS collector writes SQLite output successfully.
|
||||||
|
- Qualitative sell workflow runs without seed-file failure.
|
||||||
|
|
||||||
|
## After merge
|
||||||
|
|
||||||
|
- Re-run the two Gitea dispatch smoke tests on `main`.
|
||||||
|
- Verify the runner sees the same seed behavior on `main`.
|
||||||
|
- Keep `GatherTradingData.xlsx` untracked unless a future workflow explicitly requires it in checkout.
|
||||||
|
|
||||||
Reference in New Issue
Block a user