docs: add DAILY-FLOW and PHASE-FLOW documentation#18
Closed
w7-mgfcode wants to merge 2 commits into
Closed
Conversation
- DAILY-FLOW.md: Daily development workflow (branch strategy, PR flow, commands) - PHASE-FLOW.md: Phase completion workflow (lifecycle, snapshot, sync) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Reviewer's GuideAdds two new documentation guides describing the daily development workflow and the phase completion workflow (including branching, release, CI, and snapshot processes) for the ForecastLabAI project. Sequence diagram for the phase snapshot workflowsequenceDiagram
actor Developer
participant Git as Git_Repository
participant GitHub as GitHub_Repo
participant CI as CI_Workflows
participant Snapshot as Phase_Snapshot_Workflow
Developer->>Git: git checkout main
Developer->>Git: git pull origin main
Developer->>Git: git checkout -b phase-N
Developer->>GitHub: git push origin phase-N
GitHub->>CI: Trigger phase-snapshot.yml
CI->>Snapshot: Start phase snapshot job
Snapshot->>Snapshot: Run lint check
Snapshot->>Snapshot: Run type checks
Snapshot->>Snapshot: Run migration check
Snapshot->>Snapshot: Run unit and integration tests
Snapshot->>Snapshot: Generate metadata JSON
Snapshot->>Snapshot: Collect validation results
Snapshot->>Snapshot: Create markdown report
Snapshot->>GitHub: Upload audit artifact
Snapshot->>GitHub: Create annotated tag
CI-->>Developer: Report workflow status
Flow diagram for the daily development workflowflowchart TD
A[Start day
Update dev branch] --> B[Create feature branch
feat/prp-X-feature-name]
B --> C[Implement changes
Regular commits]
C --> D[Run local checks
ruff, mypy, pyright, pytest]
D --> E{Local checks
all pass}
E -- No --> C
E -- Yes --> F[Push feature branch
to origin]
F --> G[Create PR
base dev]
G --> H[CI pipeline
lint, type, tests,
migration, review]
H --> I{CI and review
successful}
I -- No --> G
I -- Yes --> J[Merge PR
into dev
squash, delete branch]
J --> K{Feature
complete}
K -- No --> B
K -- Yes --> L[Create PR
dev to main]
L --> M[CI on main PR]
M --> N{CI passes}
N -- No --> L
N -- Yes --> O[Merge PR
into main]
O --> P[release-please
creates Release PR]
P --> Q[CI on Release PR]
Q --> R{CI passes}
R -- No --> P
R -- Yes --> S[Merge Release PR
GitHub Release + tag]
S --> T[End
production release ready]
Flow diagram for the phase completion lifecycleflowchart TD
A[Start Phase<br/>features planned] --> B[Development<br/>feat/* branches<br/>target dev]
B --> C[Integration<br/>merge dev into main]
C --> D[Release<br/>release-please<br/>Release PR + tag]
D --> E[Documentation<br/>update PHASE-index.md<br/>update phase docs]
E --> F[Snapshot<br/>create phase-N<br/>from main]
F --> G[Phase snapshot workflow<br/>full validation<br/>audit snapshot<br/>annotated tag]
G --> H[Sync<br/>phase-N to dev<br/>ready for next phase]
H --> I{Next phase<br/>planned}
I -- Yes --> B
I -- No --> J[Project idle]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughTwo new documentation files added detailing ForecastLabAI operational procedures: DAILY-FLOW.md covers branch strategy, daily development cycle, release flow, and commit conventions; PHASE-FLOW.md documents phase completion workflows, lifecycle management, snapshot validation, and troubleshooting guidance. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@docs/PHASE-FLOW.md`:
- Around line 124-132: Reorder the two sync examples so the safer PR-based
workflow (the gh pr create --base dev --head phase-N --title "sync: update dev
from phase-N") appears first, followed by the destructive approach; keep the
destructive git reset --hard phase-N and git push origin dev --force example but
label it clearly as dangerous (e.g., add "DANGEROUS: force pushes" or similar)
and include a brief warning about disrupting teammates before that snippet;
ensure references to the commands git reset --hard, git push --force and gh pr
create remain unchanged so reviewers can locate the examples.
- Around line 219-243: Add explicit team-coordination warnings before each
destructive command block under the headings "Phase branch behind main", "Dev
diverged from main", and "Régi phase tag törlése": insert a short notice (e.g.,
"⚠️ Csak akkor használd, ha biztos vagy benne, hogy nincs mentetlen munka! /
Coordinate with your team before running destructive commands (force-push, hard
reset, delete).") immediately above the bash fences so readers must acknowledge
the risk before the commands in those sections.
🧹 Nitpick comments (3)
docs/DAILY-FLOW.md (1)
88-88: Consider clarifying why--delete-branchis omitted.Unlike the feature branch merge at line 70, this merge command doesn't include
--delete-branch. While this is correct (sincedevis a persistent branch), adding a brief comment would improve clarity for readers who might wonder about the difference.📝 Suggested clarification
# CI ellenőrzések után merge -gh pr merge <PR_NUMBER> --squash +gh pr merge <PR_NUMBER> --squash # dev branch marad (persistent)docs/PHASE-FLOW.md (2)
9-33: Specify language for code block.The ASCII diagram code block should specify a language identifier (or use
text) for better rendering and linting compliance.📝 Suggested fix
-``` +```text ┌─────────────────────────────────────────────────────────────────┐ │ PHASE LIFECYCLE │
166-193: Specify language for code block.The markdown checklist code block should specify
markdownas the language identifier for better rendering and linting compliance.📝 Suggested fix
-```markdown +````markdown ## Phase N Completion Checklist ### DevelopmentOr if nesting is an issue, simply:
-```markdown +```md
Comment on lines
+124
to
+132
| # Szinkronizáld dev-et a phase branch-ről | ||
| git checkout dev | ||
| git reset --hard phase-N | ||
| git push origin dev --force | ||
|
|
||
| # VAGY PR-rel (biztonságosabb) | ||
| gh pr create --base dev --head phase-N \ | ||
| --title "sync: update dev from phase-N" | ||
| ``` |
There was a problem hiding this comment.
Reconsider ordering: show the safer PR method first.
The destructive git reset --hard + force push approach is presented before the safer PR-based sync. While you note the PR method is "biztonságosabb" (safer), developers often follow the first example they see. Force pushing to dev can disrupt other team members who have that branch checked out and destroys any local uncommitted work.
♻️ Suggested reordering
-# Szinkronizáld dev-et a phase branch-ről
-git checkout dev
-git reset --hard phase-N
-git push origin dev --force
-
-# VAGY PR-rel (biztonságosabb)
+# PR-rel (ajánlott, biztonságos)
gh pr create --base dev --head phase-N \
--title "sync: update dev from phase-N"
+
+# VAGY force reset (csak ha biztosan nincs más dolgozó változás)
+# FIGYELEM: Ez törli a local uncommitted változásokat!
+git checkout dev
+git reset --hard phase-N
+git push origin dev --force🤖 Prompt for AI Agents
In `@docs/PHASE-FLOW.md` around lines 124 - 132, Reorder the two sync examples so
the safer PR-based workflow (the gh pr create --base dev --head phase-N --title
"sync: update dev from phase-N") appears first, followed by the destructive
approach; keep the destructive git reset --hard phase-N and git push origin dev
--force example but label it clearly as dangerous (e.g., add "DANGEROUS: force
pushes" or similar) and include a brief warning about disrupting teammates
before that snippet; ensure references to the commands git reset --hard, git
push --force and gh pr create remain unchanged so reviewers can locate the
examples.
Comment on lines
+219
to
+243
| ### Phase branch behind main | ||
| ```bash | ||
| # Töröld és hozd újra létre main-ről | ||
| git push origin --delete phase-N | ||
| git checkout main && git pull | ||
| git checkout -b phase-N | ||
| git push origin phase-N | ||
| ``` | ||
|
|
||
| ### Dev diverged from main | ||
| ```bash | ||
| # Reset dev to main | ||
| git checkout dev | ||
| git reset --hard origin/main | ||
| git push origin dev --force | ||
| ``` | ||
|
|
||
| ### Régi phase tag törlése | ||
| ```bash | ||
| # Töröld a remote taget | ||
| git push origin --delete phase-N-snapshot-YYYYMMDD-<sha> | ||
|
|
||
| # Töröld a local taget | ||
| git tag -d phase-N-snapshot-YYYYMMDD-<sha> | ||
| ``` |
There was a problem hiding this comment.
Add warnings about team coordination for destructive operations.
The troubleshooting section documents several destructive operations (force push, branch deletion, hard reset) without warnings about coordinating with the team first. These operations can cause significant disruption if other developers are actively working.
📋 Suggested safety additions
## Hibaelhárítás
+> ⚠️ **FIGYELEM**: Az alábbi műveletek destructive! Mindig egyeztess a csapattal használat előtt.
+
### Phase branch behind mainAdditionally, consider adding a note before each destructive command:
### Dev diverged from main
```bash
+# ⚠️ Csak akkor használd, ha biztos vagy benne, hogy nincs mentetlen munka!
# Reset dev to main
git checkout dev🤖 Prompt for AI Agents
In `@docs/PHASE-FLOW.md` around lines 219 - 243, Add explicit team-coordination
warnings before each destructive command block under the headings "Phase branch
behind main", "Dev diverged from main", and "Régi phase tag törlése": insert a
short notice (e.g., "⚠️ Csak akkor használd, ha biztos vagy benne, hogy nincs
mentetlen munka! / Coordinate with your team before running destructive commands
(force-push, hard reset, delete).") immediately above the bash fences so readers
must acknowledge the risk before the commands in those sections.
External systems send natural keys (store_code, sku) rather than internal database IDs. The ingest service must resolve these codes to IDs and handle unknown codes gracefully by rejecting individual rows without failing the entire batch. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only
Summary by Sourcery
Document standardized development and phase completion workflows for the ForecastLabAI project.
Documentation:
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.