Development Workflow

Development Workflow

Git workflow and best practices for D1 Database Manager development.

Overview

D1 Manager follows a simplified Git workflow optimized for open-source collaboration.

Branch Strategy

Main Branch

main branch:

• Production-ready code
• Protected branch
• All changes via pull requests
• Requires code review

Feature Branches

Naming convention:

feature/feature-name
fix/bug-name
docs/documentation-update
refactor/code-improvement

Examples:

feature/cascade-simulator
fix/filter-persistence-bug
docs/update-api-reference
refactor/extract-filter-logic

Workflow Steps

1. Fork and Clone

Fork the repository:

GitHub → Fork button → Create fork

Clone your fork:

git clone https://github.com/YOUR_USERNAME/d1-manager.git
cd d1-manager

Add upstream remote:

git remote add upstream https://github.com/neverinfamous/d1-manager.git

2. Create Feature Branch

Update main:

git checkout main
git pull upstream main

Create branch:

git checkout -b feature/your-feature

3. Make Changes

Development workflow:

# Make code changes
# Test locally (see Local Development guide)
# Commit frequently with clear messages

Commit messages:

git add .
git commit -m "feat: add cascade impact simulator"

Follow Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• style: - Formatting
• refactor: - Code restructuring
• test: - Tests
• chore: - Maintenance

4. Keep Branch Updated

Sync with upstream:

git fetch upstream
git rebase upstream/main

Resolve conflicts if any:

# Fix conflicts
git add .
git rebase --continue

5. Push to Fork

First push:

git push origin feature/your-feature

After rebase:

git push origin feature/your-feature --force-with-lease

6. Create Pull Request

1. Go to original repository on GitHub
2. Click "New Pull Request"
3. Select your branch
4. Fill out PR template
5. Submit for review

Code Review Process

As Author

After submitting PR:

1. Wait for automated checks
2. Wait for maintainer review (1-3 days)
3. Address feedback promptly
4. Push updates to same branch
5. Request re-review

Responding to feedback:

• Be professional and courteous
• Ask questions if unclear
• Explain your reasoning
• Make requested changes
• Mark conversations as resolved

As Reviewer

Review checklist:

• Code quality and readability
• Tests pass
• Documentation updated
• No breaking changes (or documented)
• Follows coding standards
• No security issues
• Performance considerations

Providing feedback:

• Be constructive and specific
• Suggest improvements
• Praise good work
• Explain reasoning
• Mark comments as blocking or non-blocking

Testing Before PR

Local Testing

Minimum requirements:

# Start both dev servers
npm run dev  # Terminal 1
npx wrangler dev --config wrangler.dev.toml --local  # Terminal 2

# Test your changes thoroughly
# Check browser console for errors
# Test in multiple browsers (Chrome, Firefox)
# Test responsive design

Manual testing checklist:

• Feature works as expected
• No console errors
• No TypeScript errors
• UI looks correct in light/dark themes
• Mobile responsive
• No broken links

Optional Production Testing

Deploy to your Cloudflare account:

# Set up your own wrangler.toml
cp wrangler.toml.example wrangler.toml
# Add your configuration

# Build and deploy
npm run build
npx wrangler deploy

# Test with real D1 databases

Commit Best Practices

Commit Frequency

Commit often:

• Small, logical changes
• One feature/fix per commit
• Easier to review
• Easier to revert

Examples:

git commit -m "feat: add cascade graph visualization"
git commit -m "feat: add row count calculation"
git commit -m "feat: add export functionality"

Commit Messages

Good commit messages:

feat: add database comparison feature

- Compare schemas between two databases
- Show tables only in source/target
- Display column differences
- Include API endpoint for comparison

Bad commit messages:

fixed stuff
update
wip
.

Squashing Commits

Before merging:

• May be asked to squash commits
• Combines multiple commits into one
• Cleaner history

Interactive rebase:

git rebase -i HEAD~3  # Last 3 commits
# Mark commits to squash
# Update commit message
git push --force-with-lease

Handling Conflicts

Merge Conflicts

When rebasing:

git fetch upstream
git rebase upstream/main

# If conflicts occur:
# 1. Fix conflicts in files
# 2. Stage resolved files
git add .
# 3. Continue rebase
git rebase --continue

# If too complex:
git rebase --abort
# Ask for help

Prevention

Keep branch updated:

# Sync regularly with upstream
git fetch upstream
git rebase upstream/main
git push --force-with-lease

Release Process

Maintainers only:

1. Update VERSION file
2. Update CHANGELOG.md
3. Create release tag
4. Build and deploy
5. Update documentation
6. Announce release

Common Scenarios

Scenario 1: Update PR After Feedback

# Make requested changes
git add .
git commit -m "fix: address review feedback"
git push origin feature/your-feature

Scenario 2: Sync with Upstream

git fetch upstream
git rebase upstream/main
git push origin feature/your-feature --force-with-lease

Scenario 3: Fix Commit Message

# Last commit only
git commit --amend -m "feat: corrected commit message"
git push --force-with-lease

Scenario 4: Add Forgotten Changes

# Make additional changes
git add .
git commit --amend --no-edit
git push --force-with-lease

Tips & Tricks

Useful Git Commands

Check status:

git status
git log --oneline

Undo changes:

git checkout -- file.txt  # Undo unstaged changes
git reset HEAD file.txt   # Unstage file
git reset --soft HEAD~1   # Undo last commit, keep changes

Stash changes:

git stash         # Save changes temporarily
git stash pop     # Restore stashed changes
git stash list    # List stashes

Cherry-pick commit:

git cherry-pick <commit-hash>

GitHub CLI

Install:

# macOS
brew install gh

# Windows
winget install GitHub.cli

Usage:

gh pr create      # Create PR from command line
gh pr list        # List PRs
gh pr checkout 123  # Checkout PR #123

Continuous Integration

Automated checks:

• TypeScript compilation
• ESLint checks
• Build successful
• Tests pass (if any)

All checks must pass before merge.

Documentation Updates

Always update docs when:

• Adding new features
• Changing APIs
• Modifying configuration
• Fixing bugs affecting usage

Files to check:

• README.md
• Wiki pages
• Code comments
• CHANGELOG.md

Getting Help

If stuck:

• Ask in PR comments
• Open a discussion on GitHub
• Check existing issues
• Review documentation

Next Steps

• Contributing Guide - Contribution guidelines
• Code Style Guide - Coding standards
• Testing Guide - Testing procedures
• Local Development - Development setup

---

Happy coding! 🚀