Skip to content

Commit 9b97df8

Browse files
chutch3chutch3
committed
fix: resolve CI/CD and documentation workflow issues
1 parent 6139b3d commit 9b97df8

8 files changed

Lines changed: 471 additions & 166 deletions

File tree

‎.cursor/rules/README.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Cursor Rules Overview
2+
3+
This directory defines **enforceable coding and workflow rules** for agents and humans working in this repository.
4+
The rules are modular, following [Cursor Context Rules](https://docs.cursor.com/en/context/rules) best practices.
5+
6+
---
7+
8+
## 📜 Rule Files
9+
10+
### 1. `tdd_enforcement.mdc`
11+
**Purpose:** Enforces **Strict TDD (Red → Green → Refactor)** for all code changes.
12+
13+
Key points:
14+
- **RED:** Write failing tests first.
15+
- **GREEN:** Implement minimum code to pass tests.
16+
- **REFACTOR:** Clean up while all tests pass.
17+
- No marking GREEN complete with failing relevant tests.
18+
- Must resolve root causes, no shortcuts.
19+
- TDD is **iterative** — multiple cycles may occur in the same branch.
20+
- Logs phase, cycle number, and violations in the **State Log**.
21+
22+
---
23+
24+
### 2. `branch_commit_pr.mdc`
25+
**Purpose:** Enforces branching, commit, and PR hygiene.
26+
27+
Key points:
28+
- Create a new branch **before starting on a new issue**.
29+
- One branch and one PR per issue.
30+
- PR must list TDD cycles performed and link to the **State Log**.
31+
- Commit frequently, use **Conventional Commits** format.
32+
- Keep commits single-line and changes simple.
33+
34+
---
35+
36+
### 3. `state_tracking.mdc`
37+
**Purpose:** Defines a **unified logging format** for all workflow tracking.
38+
39+
Key points:
40+
- **State Log** includes:
41+
- Cycle number
42+
- Current phase (RED, GREEN, or REFACTOR)
43+
- Timestamps
44+
- Commit history
45+
- Relevant test results
46+
- Violations + corrective actions
47+
- Update log at **end of every phase** and on **violations**.
48+
- Log must be accessible to reviewers (e.g., linked in PR).
49+
50+
---
51+
52+
## 🛠 How They Work Together
53+
1. **`tdd_enforcement.mdc`** ensures the *process* is followed.
54+
2. **`branch_commit_pr.mdc`** enforces *version control hygiene*.
55+
3. **`state_tracking.mdc`** standardizes *logging and visibility*.
56+
57+
Together, they guarantee:
58+
- Every change is **test-driven**.
59+
- Every workflow step is **documented**.
60+
- Every PR is **traceable and reviewable**.
61+
62+
---
63+
64+
## ✅ Compliance Checklist
65+
- [ ] New branch created before starting work.
66+
- [ ] Failing test written before implementation.
67+
- [ ] GREEN phase only marked complete with all relevant tests passing.
68+
- [ ] REFACTOR phase keeps all tests passing.
69+
- [ ] Commits are small, frequent, and follow Conventional Commits.
70+
- [ ] State Log updated at every phase and linked in PR.
71+
72+
---
73+
74+
*These rules are enforced automatically by Cursor agents but are also expected to be followed by human contributors.*

‎.cursor/rules/branch_commit_pr.mdc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
description: "Branching, commit, and PR policy"
3+
globs: ["**/*.js", "**/*.ts", "**/*.tsx", "**/*.py", "**/*.java", "**/*.md", "**/*.sh"]
4+
alwaysApply: true
5+
---
6+
7+
# BRANCHING, COMMIT, AND PR RULES
8+
9+
## 1. Branch Management
10+
- **Before starting a new issue**, create and check out a new branch.
11+
- Use clear branch naming conventions tied to the issue number.
12+
13+
## 2. Pull Request Guidelines
14+
- Open one PR per issue.
15+
- PR must include:
16+
- A summary of the changes.
17+
- A list of TDD cycles performed.
18+
- A link to the state log.
19+
20+
## 3. Commit Rules
21+
- Commit frequently.
22+
- Each commit message:
23+
- Must be a single line.
24+
- Must follow **Conventional Commits** format.
25+
- Always choose the simplest possible solution.

‎.cursor/rules/state_tracking.mdc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
description: "Unified state tracking format for TDD cycles, commits, and violations"
3+
globs: ["**/*"]
4+
alwaysApply: true
5+
---
6+
7+
# STATE TRACKING & LOGGING REQUIREMENTS
8+
9+
## 1. State Log Structure
10+
The state log must include, at a minimum:
11+
- **Cycle number** (increment for each Red/Green/Refactor iteration)
12+
- **Current phase** (RED, GREEN, or REFACTOR)
13+
- **Timestamp** of last action
14+
- **Commit history** (with commit messages and hashes)
15+
- **Relevant test results**:
16+
- Pass/fail status for directly affected test files
17+
- Summary of total passed/failed tests in this cycle
18+
- **Violations**:
19+
- Description of the violation
20+
- Root cause
21+
- Corrective action taken
22+
23+
## 2. Update Requirements
24+
- Update the state log at the end of each phase.
25+
- Log changes **immediately** when:
26+
- A violation is detected
27+
- A new commit is made
28+
- A cycle restarts
29+
30+
## 3. Accessibility
31+
- State log must be accessible to reviewers via:
32+
- A link in the PR description
33+
- Local file reference (if working offline)
34+
35+
## 4. Automation
36+
- If automated correction is possible:
37+
- Apply the correction
38+
- Log the fix and the exact changes made
39+
- Never silently bypass or hide violations.

‎.cursor/rules/tdd_enforement.mdc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
description: "Strict TDD Red/Green/Refactor workflow and test validation rules"
3+
globs: ["**/*.js", "**/*.ts", "**/*.tsx", "**/*.py", "**/*.java", "**/*.go", "**/*.sh",]
4+
alwaysApply: true
5+
---
6+
7+
# STRICT TDD WORKFLOW
8+
9+
## 1. Red/Green/Refactor Process
10+
- Apply **Red → Green → Refactor** for all code changes.
11+
- **RED**: Write one or more failing tests first for new behavior.
12+
- **GREEN**: Implement the minimum code to make the new tests pass.
13+
- **REFACTOR**: Clean up the code while keeping all tests passing.
14+
- Skip this process only for *pure analysis* or *validation* tasks.
15+
16+
## 2. Test Passing Requirements
17+
- At the end of **every** Red/Green/Refactor cycle:
18+
- All tests directly related to the implementation change must be passing.
19+
- No marking the GREEN phase complete if related tests are failing.
20+
- Resolve the **root cause** of any failure—no shortcuts or bypasses.
21+
22+
## 3. Iterative Nature
23+
- TDD is **iterative**:
24+
- Multiple Red/Green/Refactor cycles may occur within the same branch or PR.
25+
- Each new failing test restarts the cycle.
26+
- Maintain a **cycle number** for each iteration in the state log.
27+
28+
## 4. State Tracking
29+
- Track in a persistent log:
30+
- Current phase (RED, GREEN, or REFACTOR)
31+
- Current cycle number
32+
- Relevant test results
33+
- Any detected violations and their corrections
34+
- If a violation is detected:
35+
- Automatically correct it.
36+
- Log the violation and the corrective action.

‎.github/workflows/ci-cd.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,6 @@ jobs:
122122

123123
- name: Run Semantic Release
124124
id: release
125-
uses: python-semantic-release/python-semantic-release@v10.3.1
125+
uses: python-semantic-release/python-semantic-release@v9.10.0
126126
with:
127127
github_token: ${{ secrets.GITHUB_TOKEN }}
128-
build: false

‎.github/workflows/docs.yml‎

Lines changed: 24 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,15 @@ concurrency:
2727
cancel-in-progress: false
2828

2929
jobs:
30-
build:
31-
name: 🏗️ Build Documentation
32-
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
30+
# Validate documentation on PRs and pushes (non-strict mode)
31+
validate:
32+
name: 🔍 Validate Documentation
3333
runs-on: ubuntu-latest
3434
steps:
3535
- name: 📥 Checkout
3636
uses: actions/checkout@v4
3737
with:
38-
fetch-depth: 0 # Fetch full history for git plugins
38+
fetch-depth: 0
3939

4040
- name: 🐍 Set up Python
4141
uses: actions/setup-python@v5
@@ -66,32 +66,26 @@ jobs:
6666
if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
6767
run: task install
6868

69-
- name: 📚 Build documentation
70-
run: task docs:build
69+
- name: 🔍 Validate documentation build
70+
run: task docs:validate
7171

72-
- name: 📤 Upload documentation artifacts
73-
uses: actions/upload-pages-artifact@v3
72+
- name: 📤 Upload documentation artifact (for PRs)
73+
if: github.event_name == 'pull_request'
74+
uses: actions/upload-artifact@v4
7475
with:
76+
name: documentation-pr-${{ github.event.number }}
7577
path: ./site
78+
retention-days: 7
7679

77-
deploy:
78-
name: 🚀 Deploy to GitHub Pages
80+
# Build and deploy documentation only on main branch pushes
81+
build-and-deploy:
82+
name: 🏗️ Build & Deploy Documentation
7983
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
80-
needs: build
84+
needs: validate
8185
runs-on: ubuntu-latest
8286
environment:
8387
name: github-pages
8488
url: ${{ steps.deployment.outputs.page_url }}
85-
steps:
86-
- name: 🚀 Deploy to GitHub Pages
87-
id: deployment
88-
uses: actions/deploy-pages@v4
89-
90-
# Validate documentation on PRs
91-
validate:
92-
name: 🔍 Validate Documentation
93-
if: github.event_name == 'pull_request'
94-
runs-on: ubuntu-latest
9589
steps:
9690
- name: 📥 Checkout
9791
uses: actions/checkout@v4
@@ -127,10 +121,14 @@ jobs:
127121
if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
128122
run: task install
129123

130-
- name: 🔍 Validate documentation build
124+
- name: 📚 Build documentation (non-strict for deployment)
131125
run: task docs:validate
132126

133-
- name: 🔗 Check for broken links
134-
run: |
135-
# Install linkchecker if needed for future validation
136-
echo "✅ Documentation builds successfully"
127+
- name: 📤 Upload documentation artifacts
128+
uses: actions/upload-pages-artifact@v3
129+
with:
130+
path: ./site
131+
132+
- name: 🚀 Deploy to GitHub Pages
133+
id: deployment
134+
uses: actions/deploy-pages@v4

0 commit comments

Comments
 (0)