From 768ff07c99f8c56662222e13a9417816dfa6c22c Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 19:50:46 +0000 Subject: [PATCH 1/5] fix(build): align project name with actual source directory Changed PROJECT variable from 'technical-documentation' to 'docs' to match the actual source directory structure. This fixes the build failure where build-diagrams.py was looking for diagrams in /workspace/technical-documentation/diagrams but the actual source is in /workspace/docs/diagrams. The output file names remain unchanged (build/technical-documentation.pdf) as they are controlled by the OUT variable, not the PROJECT variable. Fixes #22 --- .cursor/plans/issue-22.md | 198 ++++++++++++++++++++++++++++++++++++++ Makefile | 6 +- 2 files changed, 201 insertions(+), 3 deletions(-) create mode 100644 .cursor/plans/issue-22.md diff --git a/.cursor/plans/issue-22.md b/.cursor/plans/issue-22.md new file mode 100644 index 0000000..f90ec50 --- /dev/null +++ b/.cursor/plans/issue-22.md @@ -0,0 +1,198 @@ +# Issue #22: Fix build system project directory mismatch + +## Problem Statement + +The build system has a structural inconsistency where the project name (`technical-documentation`) doesn't match the actual source directory (`docs/`), causing build failures when compiling diagrams. + +## Analysis + +### Current State + +- **Makefile line 8**: `PROJECT ?= technical-documentation` +- **Makefile line 15**: `TECH_DOC_SRC = docs/main.typ` (source is in `docs/`) +- **build-diagrams.py lines 211-212**: Expects project directory at `/workspace/{PROJECT}/` +- **Actual structure**: + - ✅ `/workspace/docs/` - Real documentation source + - ✅ `/workspace/docs/diagrams/` - Real diagrams + - ❌ `/workspace/technical-documentation/` - Expected but doesn't exist + - ❌ `/workspace/technical-documentation/build/` - Orphaned directory + +### Error Manifestation + +When running `make`, the build fails at: + +```text +📊 Compiling diagrams for technical-documentation... +Building diagrams for project: technical-documentation +Error: project directory not found at /workspace/technical-documentation +``` + +### Required Changes + +The `build-diagrams.py` script expects: + +```python +project_dir = project_root / args.project # /workspace/technical-documentation +diagrams_dir = project_dir / "diagrams" # /workspace/technical-documentation/diagrams +``` + +But the actual structure is: +- Source: `/workspace/docs/main.typ` +- Diagrams: `/workspace/docs/diagrams/` + +## Implementation Options + +### Option 1: Change Project Name to Match Directory (Recommended) + +**Description:** Update the Makefile to use "docs" as the project name instead of "technical-documentation" + +**Pros:** +- Minimal changes (only 2 lines in Makefile) +- Aligns project name with actual directory structure +- No impact on output file names or locations +- Low risk of breaking existing workflows + +**Cons:** +- Project name becomes less descriptive ("docs" vs "technical-documentation") + +**Estimated Complexity:** Low + +**Files to modify:** +- `Makefile` (lines 8, 46) + +### Option 2: Rename docs/ to technical-documentation/ + +**Description:** Rename the `docs/` directory to `technical-documentation/` to match the project name + +**Pros:** +- More descriptive directory name +- Project name remains descriptive + +**Cons:** +- Requires updating multiple file paths (TECH_DOC_SRC, README references, etc.) +- May break existing documentation or user expectations +- Higher risk of missing references +- More disruptive change + +**Estimated Complexity:** Medium + +**Files to modify:** +- `Makefile` (line 15) +- Any documentation referencing `docs/` +- Git history shows `docs/` as established directory + +### Option 3: Add Project Name Mapping to build-diagrams.py + +**Description:** Modify `build-diagrams.py` to support a mapping between project names and actual directories + +**Pros:** +- Keeps project name descriptive +- Keeps directory name conventional (`docs/`) +- Allows for flexible mappings + +**Cons:** +- Adds complexity to the build system +- Non-obvious mapping for future maintainers +- Other scripts might have same issue +- Requires more code changes + +**Estimated Complexity:** Medium + +**Files to modify:** +- `scripts/build-diagrams.py` +- Potentially other build scripts + +## Recommended Approach + +**Choice:** Option 1 - Change Project Name to Match Directory + +**Rationale:** +- Simplest solution (2-line change) +- Lowest risk +- Aligns with principle: "Make the code match reality, not reality match the code" +- The project name is primarily an internal build variable, not user-facing +- Output files still use descriptive name: `build/technical-documentation.pdf` +- The `docs/` directory is a standard convention in many projects + +## Implementation Steps + +1. ✅ **Update Makefile line 8** - Change default project name + + ```makefile + # From: + PROJECT ?= technical-documentation + # To: + PROJECT ?= docs + ``` + +2. ✅ **Update Makefile line 46** - Update technical-documentation target + + ```makefile + # From: + @$(MAKE) build-project SRC=$(TECH_DOC_SRC) OUT=$(TECH_DOC_OUT) PROJECT=technical-documentation + # To: + @$(MAKE) build-project SRC=$(TECH_DOC_SRC) OUT=$(TECH_DOC_OUT) PROJECT=docs + ``` + +3. **Test the build** - Verify diagrams compile correctly + + ```bash + make clean + make + ``` + +4. **Verify outputs** - Check that all outputs are created correctly + - `build/technical-documentation.pdf` + - `build/technical-documentation.html` + - `build/diagrams/*.svg` (compiled from `docs/diagrams/`) + +5. **Update CHANGELOG.md** - Document the fix + +6. **Commit changes** - Following conventional commit format + +## Testing Strategy + +### Pre-test Verification + +- [ ] Check that `docs/diagrams/` directory exists +- [ ] Verify `.typ` diagram files are in `docs/diagrams/` + +### Build Tests + +- [ ] `make clean` - Clean all artifacts +- [ ] `make colors` - Generate color files +- [ ] `make diagrams PROJECT=docs` - Compile diagrams explicitly +- [ ] `make` - Full build (should now succeed) + +### Output Verification + +- [ ] `build/technical-documentation.pdf` exists +- [ ] `build/technical-documentation.html` exists +- [ ] `docs/build/diagrams/` contains compiled SVGs +- [ ] Both light and dark theme SVGs are generated + +### Manual Verification + +- [ ] Open PDF - diagrams are displayed correctly +- [ ] Open HTML in browser - diagrams render with theme switching + +## Acceptance Criteria + +- [x] Makefile updated with correct project name +- [ ] Build completes without "project directory not found" error +- [ ] Diagrams compile from `docs/diagrams/` directory +- [ ] Output files are created in correct locations +- [ ] Both light and dark theme diagram SVGs are generated +- [ ] PDF and HTML outputs display diagrams correctly +- [ ] CHANGELOG.md updated with fix +- [ ] Changes committed with proper conventional commit message + +## Related Issues/PRs + +- Fixes #22 + +## Follow-up Actions (Not in this PR) + +- Consider removing orphaned `/workspace/technical-documentation/` directory +- Update documentation if PROJECT variable is referenced elsewhere +- Consider adding validation to prevent similar mismatches diff --git a/Makefile b/Makefile index 0b93cdb..80f4f49 100644 --- a/Makefile +++ b/Makefile @@ -4,8 +4,8 @@ .PHONY: all clean colors diagrams pdf html help check test example technical-documentation rebuild install-hook build-project build-summary check-outputs clean-outputs clean-generated server-start server-stop server-status version bump-patch bump-minor bump-major -# Default project -PROJECT ?= technical-documentation +# Default project (matches the actual source directory) +PROJECT ?= docs # Theme toggle configuration # Set to "yes" to include theme toggle button, "no" to use auto (system settings only) @@ -43,7 +43,7 @@ technical-documentation: @echo "==================================================" @echo "🚀 Building Technical Documentation Project" @echo "==================================================" - @$(MAKE) build-project SRC=$(TECH_DOC_SRC) OUT=$(TECH_DOC_OUT) PROJECT=technical-documentation + @$(MAKE) build-project SRC=$(TECH_DOC_SRC) OUT=$(TECH_DOC_OUT) PROJECT=docs @$(MAKE) server-start @$(MAKE) build-summary OUT=$(TECH_DOC_OUT) @echo "🌓 Toggle dark mode with the button in top-right" From 40aabf889075e8d809747b6c36d4a41955fe9f72 Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 19:54:46 +0000 Subject: [PATCH 2/5] docs: move VERSION_MANAGEMENT.md to .cursor/ directory Relocate VERSION_MANAGEMENT.md from docs/ to .cursor/ as it is development/process documentation rather than user-facing content. The .cursor/ directory is the appropriate location for workflow documentation and development tooling. Updated all references: - .cursor/commands/create-pr.md - .cursor/commands/tag-and-release.md - CHANGELOG.md Related to #22 (documentation cleanup on same branch) --- {docs => .cursor}/VERSION_MANAGEMENT.md | 0 .cursor/commands/create-pr.md | 2 +- .cursor/commands/tag-and-release.md | 4 ++-- CHANGELOG.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) rename {docs => .cursor}/VERSION_MANAGEMENT.md (100%) diff --git a/docs/VERSION_MANAGEMENT.md b/.cursor/VERSION_MANAGEMENT.md similarity index 100% rename from docs/VERSION_MANAGEMENT.md rename to .cursor/VERSION_MANAGEMENT.md diff --git a/.cursor/commands/create-pr.md b/.cursor/commands/create-pr.md index de30817..fc7d01d 100644 --- a/.cursor/commands/create-pr.md +++ b/.cursor/commands/create-pr.md @@ -8,7 +8,7 @@ For complete documentation on pull request guidelines, templates, and review pro - **[Pull Request Guidelines](./../pr-template.md)** - **[Git Workflow](./../git-workflow.md)** -- **[Version Management](./../../docs/VERSION_MANAGEMENT.md)** +- **[Version Management](./../VERSION_MANAGEMENT.md)** ## Workflow diff --git a/.cursor/commands/tag-and-release.md b/.cursor/commands/tag-and-release.md index 4f41508..438e2a9 100644 --- a/.cursor/commands/tag-and-release.md +++ b/.cursor/commands/tag-and-release.md @@ -654,7 +654,7 @@ gh release delete 0.3.3 --yes - **[git-commit.md](./git-commit.md)**: Commit changes before release - **[create-pr.md](./create-pr.md)**: Create PR with version bumping -- **[Version Management](./../../docs/VERSION_MANAGEMENT.md)**: Version management system docs +- **[Version Management](./../VERSION_MANAGEMENT.md)**: Version management system docs ## Quick Reference @@ -700,4 +700,4 @@ make bump-major # 0.3.3 → 1.0.0 --- -**For version management details, see [docs/VERSION_MANAGEMENT.md](./../../docs/VERSION_MANAGEMENT.md)** +**For version management details, see [VERSION_MANAGEMENT.md](./../VERSION_MANAGEMENT.md)** diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e11d69..15d85fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,7 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `make bump-patch`: Bump patch version (0.3.2 → 0.3.3) - `make bump-minor`: Bump minor version (0.3.2 → 0.4.0) - `make bump-major`: Bump major version (0.3.2 → 1.0.0) - - `docs/VERSION_MANAGEMENT.md`: Comprehensive documentation + - `VERSION_MANAGEMENT.md`: Comprehensive documentation - Single source of truth approach with pyproject.toml - Release workflow guidelines - Best practices for version management From a45627653f49903ddef209cdf36b9392fa419445 Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 19:55:20 +0000 Subject: [PATCH 3/5] docs(changelog): add entry for issue #22 build system fix --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 15d85fc..96a06b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Cleaner git history - no post-merge version bump commits - Integrated workflow: create-pr bumps version → merge PR → tag-and-release creates release +### Fixed + +- **Build System**: Aligned PROJECT variable with actual source directory (#22) + - Changed Makefile PROJECT from `technical-documentation` to `docs` + - Resolves build failure where build-diagrams.py couldn't find project directory + - Build now correctly looks for diagrams in `/workspace/docs/diagrams` + ## [0.3.3] - 2025-11-10 ### Added From 9b013687fd0bc45441b0e93d45499fccc9d0eba7 Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 20:01:10 +0000 Subject: [PATCH 4/5] chore(release): bump version to 0.4.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Version bump: 0.4.0 → 0.4.1 Type: patch Build system bug fix (issue #22). CHANGELOG entry already added in previous commit, consolidated into proper [0.4.1] section. --- CHANGELOG.md | 16 +++++++++------- pyproject.toml | 2 +- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96a06b3..0dae43a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,15 @@ All notable changes to this template will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.4.1] - 2025-11-10 + +### Fixed + +- **Build System**: Aligned PROJECT variable with actual source directory (#22) + - Changed Makefile PROJECT from `technical-documentation` to `docs` + - Resolves build failure where build-diagrams.py couldn't find project directory + - Build now correctly looks for diagrams in `/workspace/docs/diagrams` + ## [0.4.0] - 2025-11-10 ### Added @@ -36,13 +45,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Cleaner git history - no post-merge version bump commits - Integrated workflow: create-pr bumps version → merge PR → tag-and-release creates release -### Fixed - -- **Build System**: Aligned PROJECT variable with actual source directory (#22) - - Changed Makefile PROJECT from `technical-documentation` to `docs` - - Resolves build failure where build-diagrams.py couldn't find project directory - - Build now correctly looks for diagrams in `/workspace/docs/diagrams` - ## [0.3.3] - 2025-11-10 ### Added diff --git a/pyproject.toml b/pyproject.toml index bd9023a..8fecff6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ [project] name = "workspace" -version = "0.4.0" +version = "0.4.1" description = "workspace - Python project" requires-python = ">=3.12" dependencies = [ From a78ef36ec06a33f15fa4e933fa70d235ea039ffc Mon Sep 17 00:00:00 2001 From: gerchowl Date: Mon, 10 Nov 2025 20:06:07 +0000 Subject: [PATCH 5/5] docs(workflow): clarify version bump order in create-pr Add note that version bump happens first, then CHANGELOG editing, to make the workflow sequence clearer for users following the create-pr command. --- .cursor/commands/create-pr.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.cursor/commands/create-pr.md b/.cursor/commands/create-pr.md index fc7d01d..2355488 100644 --- a/.cursor/commands/create-pr.md +++ b/.cursor/commands/create-pr.md @@ -23,6 +23,7 @@ When creating a pull request, follow these steps: **IMPORTANT:** Version bump and CHANGELOG update happen **during PR creation**, not after merge. After PR is merged to main, run `/tag-and-release` directly to create the git tag and GitHub release. +We start with version bump only then edit the changelog **AI analyzes your changes, suggests version bump, and generates CHANGELOG:**