Skip to content

docs: Update development process and fix feature spec workflow#20

Merged
hangtime79 merged 1 commit intomasterfrom
feature/update-development-process-docs
Dec 1, 2025
Merged

docs: Update development process and fix feature spec workflow#20
hangtime79 merged 1 commit intomasterfrom
feature/update-development-process-docs

Conversation

@hangtime79
Copy link
Copy Markdown
Owner

@hangtime79 hangtime79 commented Dec 1, 2025

Summary

Replaces incorrect Reusable_Workflows branch references with correct master-based workflow across all feature specifications and adds comprehensive development process documentation.

Problem Identified

All 34 feature specifications referenced a Reusable_Workflows branch that:

  • Was a temporary development branch merged on Nov 29
  • No longer exists as an active development branch
  • Caused confusion about the correct git workflow
  • Would have led to merge conflicts

Root Cause: Feature specs were created shortly after the Reusable_Workflows branch was merged, and used it as a template without updating to the actual workflow.

Solution

📚 New Documentation Created

  1. DEVELOPMENT_PROCESS.md (Comprehensive Guide)

    • Pre-development checklist (check for open PRs - STOP if any exist!)
    • Correct git workflow using master branch
    • Step-by-step instructions
    • Troubleshooting section
    • Quick reference guide

  2. PROCESS_UPDATE_SUMMARY.md (Change Summary)

    • Before/after comparison
    • List of all files updated
    • Rationale for changes

  3. REUSABLE_WORKFLOWS_INVESTIGATION.md (Investigation Report)

    • Traced origin of Reusable_Workflows references
    • Git history analysis
    • Confirmed orchestrate_phases.py is correct (no changes needed)
    • Detailed findings

  4. update_specs.py (Automation Script)

    • Python script used to update all 34 feature specs
    • Can be reused for future bulk updates
    • Properly formatted with black and ruff

Changes Made

Before (Incorrect) ❌

## Merge Instructions

### Branch

```bash
git checkout Reusable_Workflows  # ❌ Non-existent branch
git pull origin Reusable_Workflows
git checkout -b feature/name

**Issues:**
- No check for open PRs (leads to conflicts)
- References non-existent development branch
- Unclear about base branch for PRs

### After (Correct) ✅

```bash
## Merge Instructions

**IMPORTANT:** Before starting, read `DEVELOPMENT_PROCESS.md` for complete workflow.

### Pre-Development Checklist

1. **Check for outstanding PRs:**
   ```bash
   gh pr list --repo hangtime79/dataiku-api-client-python --state open
  • If ANY open PRs exist: STOP! Wait for them to be merged first.
  • If NO open PRs: Proceed to step 2.

  1. Sync local master:

    git checkout master
git pull origin master

  2. Create feature branch from master:

    git checkout -b feature/PX-FXXX-name

Never use Reusable_Workflows branch!


**Benefits:**
- ✅ Enforces single-PR workflow (prevents conflicts)
- ✅ Uses actual master branch
- ✅ Clear, step-by-step instructions
- ✅ Links to comprehensive documentation

---

## Files Changed

### Created (4 files)
- `DEVELOPMENT_PROCESS.md` - Complete workflow guide
- `PROCESS_UPDATE_SUMMARY.md` - Change summary
- `REUSABLE_WORKFLOWS_INVESTIGATION.md` - Investigation findings
- `update_specs.py` - Automation script

### Modified (35 files)
- `README.md` - Added development process section
- **34 feature specification files** across all phases (0-12):
  - `phase-0/`: P0-F001 through P0-F004 (4 files)
  - `phase-1/`: P1-F001 through P1-F005 (5 files)
  - `phase-2/`: P2-F001 through P2-F004 (4 files)
  - `phase-3/`: P3-F001 through P3-F003 (3 files)
  - `phase-4/`: P4-F001 through P4-F003 (3 files)
  - `phase-5/`: P5-F001 through P5-F003 (3 files)
  - `phase-6/`: P6-F001 (1 file)
  - `phase-7/`: P7-F001 through P7-F004 (4 files)
  - `phase-8/`: P8-F001 through P8-F002 (2 files)
  - `phase-9/`: P9-F001 (1 file)
  - `phase-10/`: P10-F001 (1 file)
  - `phase-11/`: P11-F001 through P11-F002 (2 files)
  - `phase-12/`: P12-F001 (1 file)

**Total:** +2,100 insertions, -204 deletions

---

## Impact

### For Future Development

✅ **Clear workflow** - No confusion about git process
✅ **Prevents conflicts** - Single-PR enforcement
✅ **Consistent specs** - All 34 specs now aligned
✅ **Self-documenting** - DEVELOPMENT_PROCESS.md is comprehensive
✅ **No orchestration changes** - `orchestrate_phases.py` already correct

### For AI Agents (Claude Code)

When implementing features via `orchestrate_phases.py`:
- Pre-flight check for open PRs automatically enforced
- Always syncs from master before starting
- Clear instructions in every feature spec
- Links to comprehensive documentation

---

## Verification

### Before Merge - Check:

```bash
# 1. Verify Reusable_Workflows removed from specs
grep -r "Reusable_Workflows" dataiku-reusable-workflows/components/discovery-agent/features/ --include="*.md"
# Expected: (empty)

# 2. Verify master workflow present
grep -r "git checkout master" dataiku-reusable-workflows/components/discovery-agent/features/ --include="*.md" | wc -l
# Expected: 34

# 3. Verify PR check present
grep -r "gh pr list" dataiku-reusable-workflows/components/discovery-agent/features/ --include="*.md" | wc -l
# Expected: 34

Notes

  • orchestrate_phases.py - No changes needed (already correct)
  • Existing PRs - This change is independent and won't conflict
  • Backward compatibility - Old workflow patterns removed entirely
  • Documentation - Comprehensive and ready for use

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

@hangtime79 @claude
docs: update development process and fix feature spec workflow
00287ca 
Replace incorrect Reusable_Workflows references with correct master-based workflow.

## New Documentation

- **DEVELOPMENT_PROCESS.md**: Comprehensive workflow guide
  - Pre-development checklist (check for open PRs)
  - Step-by-step git workflow using master branch
  - Troubleshooting section
  - Quick reference guide

- **PROCESS_UPDATE_SUMMARY.md**: Summary of all changes made

- **REUSABLE_WORKFLOWS_INVESTIGATION.md**: Investigation findings
  - Traced origin of Reusable_Workflows references
  - Confirmed orchestrate_phases.py is correct
  - No changes needed to orchestration script

- **update_specs.py**: Automation script for updating feature specs

## Updated Files

- **README.md**: Added development process section with warnings
- **34 feature specification files**: Updated merge instructions
  - Removed Reusable_Workflows branch references
  - Added pre-development PR check requirement
  - Updated to use master branch workflow
  - Added reference to DEVELOPMENT_PROCESS.md

## Changes

### Before (Incorrect)
```bash
git checkout Reusable_Workflows  # ❌ Wrong branch
git pull origin Reusable_Workflows
git checkout -b feature/name
```

### After (Correct)
```bash
# 1. Check for open PRs - STOP if any exist
gh pr list --repo hangtime79/dataiku-api-client-python --state open

# 2. Sync master
git checkout master
git pull origin master

# 3. Create feature branch
git checkout -b feature/PX-FXXX-name
```

## Impact

- ✅ All 34 feature specs updated with correct workflow
- ✅ Single-PR workflow enforced
- ✅ Prevents merge conflicts
- ✅ Clear documentation for future development
- ✅ No changes to orchestrate_phases.py (already correct)

## Files Changed

**Created:**
- DEVELOPMENT_PROCESS.md (comprehensive guide)
- PROCESS_UPDATE_SUMMARY.md (change summary)
- REUSABLE_WORKFLOWS_INVESTIGATION.md (investigation report)
- update_specs.py (automation script)

**Modified:**
- README.md (added process section)
- 34 feature spec files (updated merge instructions)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
@hangtime79 hangtime79 merged commit d18c882 into master Dec 1, 2025
4 checks passed
@hangtime79 hangtime79 deleted the feature/update-development-process-docs branch December 1, 2025 12:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@hangtime79