[2026-04-28] Rename apple-browsers rules .mdc → .md for Obsidian compatibility
This commit is contained in:
Alexey Martemyanov
@@ -0,0 +1,319 @@
|
||||
---
|
||||
source: ~/DuckDuckGo/apple-browsers.git/main/.cursor/rules/branch-naming-conventions.mdc
|
||||
confidence: 0.9
|
||||
namespace: work
|
||||
last_synced: 2026-04-28
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Branch Naming Conventions & GitHub Flow
|
||||
|
||||
## Overview
|
||||
|
||||
DuckDuckGo browser development follows **GitHub Flow**, a streamlined branching strategy that maintains a single main branch with feature branches for development work.
|
||||
|
||||
**Reference**: [GitHub Flow Documentation](https://docs.github.com/en/get-started/using-github/github-flow)
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Main Branch Strategy
|
||||
- **Single source of truth**: All development branches from `main`
|
||||
- **Always deployable**: `main` branch should always be in a deployable state
|
||||
- **Merge via PR**: All changes merged back through Pull Requests (except releases)
|
||||
|
||||
### Branch Lifecycle
|
||||
1. Create branch from `main`
|
||||
2. Develop feature/fix on branch
|
||||
3. Open Pull Request to `main`
|
||||
4. Code review and testing
|
||||
5. Merge to `main`
|
||||
6. **Delete branch** immediately after merge
|
||||
|
||||
## Branch Naming Conventions
|
||||
|
||||
### Single Developer Features & Bugfixes
|
||||
|
||||
For work by a single developer:
|
||||
|
||||
```
|
||||
Format: <developer-name>/<feature-or-fix-name>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
- `alice/bookmark-sync`
|
||||
- `alice/fix-bookmark-sync`
|
||||
- `bob/credit-card-autofill`
|
||||
- `charlie/fix-crash-on-startup`
|
||||
|
||||
**Guidelines:**
|
||||
- Use kebab-case (lowercase with hyphens)
|
||||
- Be descriptive but concise
|
||||
- Include "fix-" prefix for bugfixes when helpful
|
||||
|
||||
### Multi-Developer Features
|
||||
|
||||
For collaborative features, use a two-stage approach:
|
||||
|
||||
#### 1. Base Feature Branch
|
||||
```
|
||||
Format: <feature-name>
|
||||
Example: autofill
|
||||
```
|
||||
|
||||
#### 2. Individual Developer Branches
|
||||
```
|
||||
Format: <feature-name>/<developer-name>/<sub-feature-name>
|
||||
Example: autofill/alice/settings-list-changes
|
||||
```
|
||||
|
||||
**Workflow:**
|
||||
1. Create base feature branch from `main`
|
||||
2. Developers create individual branches from base feature branch
|
||||
3. Individual branches merge into base feature branch
|
||||
4. Base feature branch merges into `main`
|
||||
|
||||
### Release Branches
|
||||
|
||||
Release branches follow semantic versioning:
|
||||
|
||||
```
|
||||
Format: release/<version>
|
||||
Example: release/0.18.5
|
||||
```
|
||||
|
||||
**Special Notes:**
|
||||
- No developer name prefix
|
||||
- Use semantic versioning format
|
||||
- **Exception**: Release branches merge to `main` via local merge (not PR)
|
||||
- Delete immediately after merge
|
||||
|
||||
### Hotfix Branches
|
||||
|
||||
Critical fixes for production issues:
|
||||
|
||||
```
|
||||
Format: hotfix/<version>
|
||||
Example: hotfix/5.50.1
|
||||
```
|
||||
|
||||
**Critical Requirements:**
|
||||
- Use hotfix version number
|
||||
- **MUST delete immediately after merge**
|
||||
- Some tooling blocks subsequent hotfixes if previous hotfix branch exists
|
||||
- Higher priority than regular releases
|
||||
|
||||
## Branch Management Best Practices
|
||||
|
||||
### ✅ DO
|
||||
|
||||
```bash
|
||||
# Create feature branch from main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b alice/new-feature
|
||||
|
||||
# Meaningful commit messages
|
||||
git commit -m "Add user authentication for secure vault"
|
||||
|
||||
# Keep branches up to date
|
||||
git rebase main # or git merge main
|
||||
|
||||
# Delete branch after merge
|
||||
git branch -d alice/new-feature
|
||||
git push origin --delete alice/new-feature
|
||||
```
|
||||
|
||||
### ❌ DON'T
|
||||
|
||||
```bash
|
||||
# Don't use unclear names
|
||||
git checkout -b temp
|
||||
git checkout -b fix
|
||||
git checkout -b test-branch
|
||||
|
||||
# Don't leave merged branches
|
||||
# (Clutters repository and can cause tooling issues)
|
||||
|
||||
# Don't work directly on main
|
||||
git checkout main
|
||||
# Edit files directly... ❌
|
||||
|
||||
# Don't use inconsistent naming
|
||||
git checkout -b Alice/NewFeature # Mixed case
|
||||
git checkout -b alice_new_feature # Underscore instead of hyphen
|
||||
```
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Single Developer Feature
|
||||
|
||||
```bash
|
||||
# Start new feature
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b alice/password-manager
|
||||
|
||||
# Work on feature
|
||||
# ... make changes ...
|
||||
git add .
|
||||
git commit -m "Implement password storage encryption"
|
||||
|
||||
# Push and create PR
|
||||
git push origin alice/password-manager
|
||||
# Create PR via GitHub UI
|
||||
|
||||
# After PR is merged, cleanup
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git branch -d alice/password-manager
|
||||
git push origin --delete alice/password-manager
|
||||
```
|
||||
|
||||
### Multi-Developer Feature
|
||||
|
||||
```bash
|
||||
# Team lead creates base branch
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b autofill
|
||||
git push origin autofill
|
||||
|
||||
# Developer creates individual branch
|
||||
git checkout autofill
|
||||
git pull origin autofill
|
||||
git checkout -b autofill/alice/credential-storage
|
||||
|
||||
# Work and merge to base feature branch
|
||||
# ... development work ...
|
||||
git push origin autofill/alice/credential-storage
|
||||
# Create PR to merge into 'autofill' branch
|
||||
|
||||
# Eventually merge base feature to main
|
||||
# Create PR from 'autofill' to 'main'
|
||||
```
|
||||
|
||||
### Hotfix Workflow
|
||||
|
||||
```bash
|
||||
# Create hotfix from main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b hotfix/5.50.1
|
||||
|
||||
# Fix critical issue
|
||||
# ... emergency fixes ...
|
||||
git commit -m "Fix critical security vulnerability"
|
||||
|
||||
# Merge and IMMEDIATELY delete
|
||||
git push origin hotfix/5.50.1
|
||||
# Create PR and merge immediately
|
||||
git branch -d hotfix/5.50.1
|
||||
git push origin --delete hotfix/5.50.1
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Feature Names
|
||||
|
||||
| Type | Good Examples | Bad Examples |
|
||||
|------|---------------|--------------|
|
||||
| **New Features** | `user-authentication`<br>`bookmark-sync`<br>`credit-card-autofill` | `feature`<br>`new-stuff`<br>`implementation` |
|
||||
| **Bug Fixes** | `fix-memory-leak`<br>`fix-crash-on-startup`<br>`fix-bookmark-deletion` | `bug`<br>`fix`<br>`temp-fix` |
|
||||
| **Improvements** | `improve-performance`<br>`optimize-database`<br>`refactor-networking` | `better`<br>`update`<br>`changes` |
|
||||
|
||||
### Developer Names
|
||||
|
||||
| Format | Example |
|
||||
|--------|---------|
|
||||
| **First name** | `alice/new-feature` |
|
||||
| **GitHub username** | `alice-dev/new-feature` |
|
||||
| **Consistent choice** | Pick one format and stick to it |
|
||||
|
||||
## Branch Protection & CI
|
||||
|
||||
### Main Branch Protection
|
||||
- **Required status checks**: All CI must pass
|
||||
- **Required reviews**: At least one approval required
|
||||
- **No force pushes**: Maintain history integrity
|
||||
- **Delete head branches**: Automatic cleanup after merge
|
||||
|
||||
### Feature Branch CI
|
||||
- Shellcheck validation for script changes
|
||||
- Unit tests must pass
|
||||
- Build verification for iOS and macOS
|
||||
- Code style validation
|
||||
|
||||
## Git Configuration Tips
|
||||
|
||||
### Helpful Git Settings
|
||||
|
||||
```bash
|
||||
# Auto-delete tracking branches for deleted remotes
|
||||
git config --global fetch.prune true
|
||||
|
||||
# Auto-setup upstream when pushing new branches
|
||||
git config --global push.autoSetupRemote true
|
||||
|
||||
# Use more descriptive default branch names
|
||||
git config --global init.defaultBranch main
|
||||
```
|
||||
|
||||
### Useful Aliases
|
||||
|
||||
```bash
|
||||
# Quick branch switching
|
||||
git config --global alias.co checkout
|
||||
git config --global alias.br branch
|
||||
|
||||
# Clean up merged branches
|
||||
git config --global alias.cleanup "!git branch --merged | grep -v '\\*\\|main\\|develop' | xargs -n 1 git branch -d"
|
||||
|
||||
# Show branch with tracking info
|
||||
git config --global alias.branches "branch -vv"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Branch Already Exists
|
||||
```bash
|
||||
# If remote branch exists but you don't have it locally
|
||||
git fetch origin
|
||||
git checkout -b alice/feature-name origin/alice/feature-name
|
||||
```
|
||||
|
||||
### Hotfix Branch Blocked
|
||||
```bash
|
||||
# If hotfix creation is blocked, check for existing hotfix branches
|
||||
git branch -r | grep hotfix
|
||||
# Delete any remaining hotfix branches
|
||||
git push origin --delete hotfix/previous-version
|
||||
```
|
||||
|
||||
### Sync with Main
|
||||
```bash
|
||||
# Keep feature branch updated with main
|
||||
git checkout alice/feature-name
|
||||
git rebase main # or: git merge main
|
||||
git push origin alice/feature-name --force-with-lease # if rebased
|
||||
```
|
||||
|
||||
## Integration with Development Tools
|
||||
|
||||
### Xcode Integration
|
||||
- Branch names appear in Xcode source control
|
||||
- Use descriptive names for better identification
|
||||
- Avoid special characters that might cause Xcode issues
|
||||
|
||||
### CI/CD Pipeline
|
||||
- Branch names used in build artifacts
|
||||
- Feature branches trigger full test suites
|
||||
- Release branches trigger deployment pipelines
|
||||
|
||||
### Issue Tracking
|
||||
- Reference GitHub issues in branch names when helpful:
|
||||
- `alice/fix-issue-1234-memory-leak`
|
||||
- `bob/feature-567-dark-mode`
|
||||
|
||||
---
|
||||
|
||||
Following these conventions ensures consistent, organized development workflow across the DuckDuckGo browser codebase and facilitates collaboration between team members.
|
||||
Reference in New Issue
Block a user