mirror of
https://github.com/The-Low-Code-Foundation/OpenNoodl.git
synced 2026-01-12 07:12:54 +01:00
Merged Axel changes. Added dev docs for Cline
This commit is contained in:
Richard Osborne
332
dev-docs/guidelines/GIT-WORKFLOW.md
Normal file
332
dev-docs/guidelines/GIT-WORKFLOW.md
Normal file
@@ -0,0 +1,332 @@
|
||||
# Git Workflow Guide
|
||||
|
||||
How to manage branches, commits, and pull requests for OpenNoodl development.
|
||||
|
||||
## Branch Naming
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
type/id-short-description
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
| Type | Use For | Example |
|
||||
|------|---------|---------|
|
||||
| `task` | Task documentation work | `task/001-dependency-updates` |
|
||||
| `feature` | New features | `feature/vercel-deployment` |
|
||||
| `fix` | Bug fixes | `fix/page-router-scroll` |
|
||||
| `refactor` | Code improvements | `refactor/property-panel-hooks` |
|
||||
| `docs` | Documentation only | `docs/api-reference` |
|
||||
| `test` | Test additions | `test/rest-node-coverage` |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Task branches (from dev-docs)
|
||||
git checkout -b task/001-dependency-updates
|
||||
git checkout -b task/002-typescript-cleanup
|
||||
|
||||
# Feature branches
|
||||
git checkout -b feature/add-oauth-support
|
||||
git checkout -b feature/multi-project-windows
|
||||
|
||||
# Fix branches
|
||||
git checkout -b fix/nested-router-scroll
|
||||
git checkout -b fix/array-change-tracking
|
||||
|
||||
# Refactor branches
|
||||
git checkout -b refactor/remove-class-components
|
||||
git checkout -b refactor/data-node-architecture
|
||||
```
|
||||
|
||||
## Commit Messages
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
type(scope): short description
|
||||
|
||||
[optional longer description]
|
||||
|
||||
[optional footer with references]
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
- `feat` - New feature
|
||||
- `fix` - Bug fix
|
||||
- `refactor` - Code restructuring (no behavior change)
|
||||
- `docs` - Documentation changes
|
||||
- `test` - Test additions/changes
|
||||
- `chore` - Build/tooling changes
|
||||
- `style` - Formatting (no code change)
|
||||
- `perf` - Performance improvement
|
||||
|
||||
### Scopes
|
||||
|
||||
Use the affected area:
|
||||
|
||||
- `editor` - Main editor code
|
||||
- `runtime` - Runtime engine
|
||||
- `viewer` - Viewer/preview
|
||||
- `ui` - Core UI components
|
||||
- `build` - Build system
|
||||
- `deps` - Dependencies
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Features
|
||||
git commit -m "feat(editor): add connection breakpoints"
|
||||
git commit -m "feat(runtime): implement retry logic for REST node"
|
||||
|
||||
# Fixes
|
||||
git commit -m "fix(viewer): resolve scroll jumping in nested routers"
|
||||
git commit -m "fix(editor): prevent crash when deleting connected node"
|
||||
|
||||
# Refactoring
|
||||
git commit -m "refactor(ui): convert PropertyPanel to functional component"
|
||||
git commit -m "refactor(runtime): simplify collection change tracking"
|
||||
|
||||
# Docs
|
||||
git commit -m "docs(readme): update installation instructions"
|
||||
git commit -m "docs(api): add JSDoc to public methods"
|
||||
|
||||
# Tests
|
||||
git commit -m "test(runtime): add unit tests for REST node"
|
||||
git commit -m "test(editor): add integration tests for import flow"
|
||||
|
||||
# Chores
|
||||
git commit -m "chore(deps): update webpack to 5.101.3"
|
||||
git commit -m "chore(build): enable source maps in development"
|
||||
```
|
||||
|
||||
### Multi-line Commits
|
||||
|
||||
For complex changes:
|
||||
|
||||
```bash
|
||||
git commit -m "feat(editor): add AI-powered node suggestions
|
||||
|
||||
- Integrate with OpenAI API for code analysis
|
||||
- Add suggestion UI in node picker
|
||||
- Cache suggestions for performance
|
||||
|
||||
Closes #123"
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
### Starting Work
|
||||
|
||||
```bash
|
||||
# 1. Ensure main is up to date
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# 2. Create your branch
|
||||
git checkout -b task/001-dependency-updates
|
||||
|
||||
# 3. Make your changes...
|
||||
|
||||
# 4. Stage and commit frequently
|
||||
git add -A
|
||||
git commit -m "feat(deps): update React to v19"
|
||||
```
|
||||
|
||||
### During Development
|
||||
|
||||
```bash
|
||||
# Check status often
|
||||
git status
|
||||
|
||||
# View your changes
|
||||
git diff
|
||||
|
||||
# Stage specific files
|
||||
git add packages/noodl-editor/package.json
|
||||
|
||||
# Commit logical chunks
|
||||
git commit -m "fix(deps): resolve peer dependency conflicts"
|
||||
|
||||
# Push to remote (first time)
|
||||
git push -u origin task/001-dependency-updates
|
||||
|
||||
# Push subsequent commits
|
||||
git push
|
||||
```
|
||||
|
||||
### Keeping Up to Date
|
||||
|
||||
```bash
|
||||
# If main has changed, rebase your work
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
|
||||
# Resolve any conflicts, then continue
|
||||
git add .
|
||||
git rebase --continue
|
||||
|
||||
# Force push after rebase (your branch only!)
|
||||
git push --force-with-lease
|
||||
```
|
||||
|
||||
### Creating Pull Request
|
||||
|
||||
1. Push your branch to remote
|
||||
2. Go to GitHub repository
|
||||
3. Click "New Pull Request"
|
||||
4. Select your branch
|
||||
5. Fill in the template:
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
Brief description of changes
|
||||
|
||||
## Task Reference
|
||||
TASK-001: Dependency Updates
|
||||
|
||||
## Changes Made
|
||||
- Updated React to v19
|
||||
- Fixed peer dependency conflicts
|
||||
- Migrated to createRoot API
|
||||
|
||||
## Testing
|
||||
- [ ] All existing tests pass
|
||||
- [ ] Manual testing completed
|
||||
- [ ] New tests added (if applicable)
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Documentation updated
|
||||
- [ ] CHANGELOG.md updated
|
||||
- [ ] No console.log statements
|
||||
```
|
||||
|
||||
### After PR Merged
|
||||
|
||||
```bash
|
||||
# Switch to main
|
||||
git checkout main
|
||||
|
||||
# Pull the merged changes
|
||||
git pull origin main
|
||||
|
||||
# Delete your local branch
|
||||
git branch -d task/001-dependency-updates
|
||||
|
||||
# Delete remote branch (if not auto-deleted)
|
||||
git push origin --delete task/001-dependency-updates
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Oops, Wrong Branch
|
||||
|
||||
```bash
|
||||
# Stash your changes
|
||||
git stash
|
||||
|
||||
# Switch to correct branch
|
||||
git checkout correct-branch
|
||||
|
||||
# Apply your changes
|
||||
git stash pop
|
||||
```
|
||||
|
||||
### Need to Undo Last Commit
|
||||
|
||||
```bash
|
||||
# Undo commit but keep changes
|
||||
git reset --soft HEAD~1
|
||||
|
||||
# Undo commit and discard changes
|
||||
git reset --hard HEAD~1
|
||||
```
|
||||
|
||||
### Need to Update Commit Message
|
||||
|
||||
```bash
|
||||
# Most recent commit
|
||||
git commit --amend -m "new message"
|
||||
|
||||
# Older commit (interactive rebase)
|
||||
git rebase -i HEAD~3
|
||||
# Change 'pick' to 'reword' for the commit
|
||||
```
|
||||
|
||||
### Accidentally Committed to Main
|
||||
|
||||
```bash
|
||||
# Create a branch with your commits
|
||||
git branch my-feature
|
||||
|
||||
# Reset main to origin
|
||||
git reset --hard origin/main
|
||||
|
||||
# Switch to your feature branch
|
||||
git checkout my-feature
|
||||
```
|
||||
|
||||
### Merge Conflicts
|
||||
|
||||
```bash
|
||||
# During rebase or merge, if conflicts occur:
|
||||
|
||||
# 1. Open conflicted files and resolve
|
||||
# Look for <<<<<<< ======= >>>>>>> markers
|
||||
|
||||
# 2. Stage resolved files
|
||||
git add resolved-file.ts
|
||||
|
||||
# 3. Continue the rebase/merge
|
||||
git rebase --continue
|
||||
# or
|
||||
git merge --continue
|
||||
```
|
||||
|
||||
## Branch Protection
|
||||
|
||||
The `main` branch has these protections:
|
||||
|
||||
- Requires pull request
|
||||
- Requires passing CI checks
|
||||
- Requires up-to-date branch
|
||||
- No force pushes allowed
|
||||
|
||||
## Tips
|
||||
|
||||
### Useful Aliases
|
||||
|
||||
Add to your `~/.gitconfig`:
|
||||
|
||||
```ini
|
||||
[alias]
|
||||
st = status
|
||||
co = checkout
|
||||
br = branch
|
||||
ci = commit
|
||||
lg = log --oneline --graph --all
|
||||
unstage = reset HEAD --
|
||||
last = log -1 HEAD
|
||||
branches = branch -a
|
||||
```
|
||||
|
||||
### Before Every PR
|
||||
|
||||
1. Run tests: `npm run test:editor`
|
||||
2. Run type check: `npx tsc --noEmit`
|
||||
3. Run linter: `npx eslint packages/ --fix`
|
||||
4. Review your diff: `git diff main`
|
||||
5. Check commit history: `git log --oneline main..HEAD`
|
||||
|
||||
### Good Commit Hygiene
|
||||
|
||||
- Commit early and often
|
||||
- Each commit should be atomic (one logical change)
|
||||
- Commits should compile and pass tests
|
||||
- Write meaningful commit messages
|
||||
- Don't commit generated files
|
||||
- Don't commit debug code
|
||||
Reference in New Issue
Block a user