diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78c5aa3..0cf30a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,9 +9,11 @@ Thank you for your interest in contributing to this project! This guide will hel - [Tech Stack](#tech-stack) - [Project Structure](#project-structure) - [Development Workflow](#development-workflow) +- [Pull Request Guidelines](#pull-request-guidelines) - [Content Workflows](#content-workflows) - [Code Style & Standards](#code-style--standards) - [Testing](#testing) +- [Legacy Code & Migration](#legacy-code--migration) - [Commit Guidelines](#commit-guidelines) ## Getting Started @@ -186,6 +188,38 @@ portfolio/ ## Development Workflow +### Branch Naming Conventions + +Use descriptive branch names that follow these patterns: + +| Branch Type | Pattern | Example | Description | +|-------------|---------|---------|-------------| +| **Feature** | `feature/` | `feature/add-dark-mode` | New features or enhancements | +| **Bug Fix** | `fix/` | `fix/mobile-nav-bug` | Bug fixes and error corrections | +| **Documentation** | `docs/` | `docs/update-readme` | Documentation updates | +| **Refactoring** | `refactor/` | `refactor/contact-form` | Code restructuring without behavior changes | +| **Testing** | `test/` | `test/add-unit-tests` | Adding or updating tests | +| **Chore** | `chore/` | `chore/update-dependencies` | Maintenance tasks, dependency updates | + +**Guidelines:** +- Use lowercase with hyphens (kebab-case) +- Keep branch names concise but descriptive (3-5 words max) +- Avoid special characters except hyphens +- Delete branches after they've been merged + +**Examples:** +```bash +# ✅ Good +git checkout -b feature/cookie-consent-banner +git checkout -b fix/portfolio-filter-crash +git checkout -b docs/api-integration-guide + +# ❌ Bad +git checkout -b myFeature +git checkout -b fix_bug +git checkout -b john-working-branch +``` + ### 1. Create a New Feature Branch ```bash git checkout -b feature/your-feature-name @@ -216,6 +250,123 @@ npm run build Ensure the build completes without errors before submitting. +### 5. Submit a Pull Request + +See the [Pull Request Guidelines](#pull-request-guidelines) section below for detailed instructions. + +## Pull Request Guidelines + +When you're ready to submit your changes, create a pull request (PR) following these guidelines to ensure a smooth review process. + +### Before Creating a PR + +**Pre-submission Checklist:** +- [ ] All tests pass (`npm test`) +- [ ] Linter runs without errors (`npm run lint`) +- [ ] Production build succeeds (`npm run build`) +- [ ] Changes have been tested locally +- [ ] Code follows project style guidelines +- [ ] No debugging statements left in code (console.log, debugger, etc.) +- [ ] Translation files updated for all locales (de, en, sr) if UI text changed +- [ ] Documentation updated if necessary + +### PR Title Format + +Use the same format as commit messages: + +``` +: +``` + +**Examples:** +``` +feat: add cookie consent banner +fix: resolve mobile navigation menu bug +docs: update API integration guide +refactor: simplify contact form validation +``` + +### PR Description Template + +Provide a clear description of your changes: + +```markdown +## Summary +Brief overview of what this PR does and why. + +## Changes Made +- Added new component for cookie consent +- Updated privacy policy page +- Added tests for consent logic + +## Testing +- [ ] Tested on desktop browsers (Chrome, Firefox, Safari) +- [ ] Tested on mobile devices +- [ ] Verified all three languages (de, en, sr) +- [ ] Checked accessibility with screen reader + +## Screenshots (if applicable) +[Add screenshots for UI changes] + +## Related Issues +Closes #123 +Related to #456 +``` + +### PR Best Practices + +1. **Keep PRs Focused** + - One feature or fix per PR + - Avoid mixing unrelated changes + - Break large features into smaller, reviewable PRs + +2. **Write Descriptive Commits** + - Follow the [Commit Guidelines](#commit-guidelines) + - Each commit should be a logical unit of work + - Avoid "WIP" or "Fix" commit messages + +3. **Update Documentation** + - Update README.md if adding new features + - Update CONTRIBUTING.md if changing development workflow + - Add JSDoc comments for new public functions + +4. **Request Review** + - Tag relevant reviewers + - Respond to review comments promptly + - Make requested changes in new commits (don't force push) + +5. **CI/CD Checks** + - Ensure all automated checks pass + - Fix any linting or build errors + - Address test failures before requesting review + +### PR Review Process + +1. **Automated Checks** - All CI/CD checks must pass +2. **Code Review** - At least one approval required +3. **Testing** - Reviewer may test changes locally +4. **Merge** - Squash and merge into main branch +5. **Cleanup** - Delete branch after merge + +### Handling Review Feedback + +- **Be responsive** - Address feedback within 1-2 days +- **Ask questions** - If feedback is unclear, ask for clarification +- **Make changes** - Commit review suggestions as new commits +- **Re-request review** - After addressing all comments +- **Be respectful** - Code reviews are about the code, not the person + +### What Gets Rejected + +PRs will be rejected or require changes if: +- ❌ Tests are failing +- ❌ Linter errors exist +- ❌ Build fails +- ❌ Breaking changes without discussion +- ❌ Missing translations for new UI text +- ❌ No description or context provided +- ❌ Touches legacy code without coordination (see [Legacy Code](#legacy-code--migration)) + ## Content Workflows This section covers how to add and manage content for portfolio projects, blog posts, and translations. The project supports multi-language content in German (de), English (en), and Serbian (sr). @@ -915,6 +1066,124 @@ While we don't enforce strict coverage requirements, aim for: Run `npm run test:coverage` to see current coverage reports. +## Legacy Code & Migration + +This project is currently undergoing a **migration from Vite + React to Next.js 15**. During this transition, you'll encounter legacy directories that contain the old Vite-based code. Understanding these directories is crucial to avoid conflicts and ensure a smooth migration process. + +### Legacy Directories + +The following directories contain **legacy code from the Vite implementation** and should be handled with care: + +| Directory | Type | Description | Status | +|-----------|------|-------------|--------| +| **`src/components-vite/`** | Components | Original Vite-based React components | ⚠️ Legacy - Being migrated | +| **`src/pages-vite/`** | Pages | Vite-based page components | ⚠️ Legacy - Being migrated | +| **`src/i18n/locales-old/`** | Translations | Old translation structure for portfolio projects | ⚠️ Legacy - Partially used | + +### What Are These Directories? + +#### `src/components-vite/` +- **Purpose:** Contains the original UI components built for the Vite + React architecture +- **Contents:** Buttons, forms, navigation, cards, and other reusable components +- **Status:** Being gradually replaced with Next.js-compatible components in `src/components/` +- **Why it exists:** Serves as reference during migration and fallback for unmigrated features + +#### `src/pages-vite/` +- **Purpose:** Original Vite page components (before Next.js App Router) +- **Contents:** Home, About, Portfolio, Blog, Contact pages and their subpages +- **Status:** Being replaced with Next.js App Router pages in `src/app/[locale]/` +- **Why it exists:** Historical reference and for any unmigrated route logic + +#### `src/i18n/locales-old/` +- **Purpose:** Legacy translation system for portfolio projects +- **Contents:** TypeScript-based portfolio project definitions (see [Adding Portfolio Projects](#adding-portfolio-projects)) +- **Status:** **Still in active use** for portfolio projects until migration to MDX is complete +- **Why it exists:** Portfolio projects are currently defined as `.ts` files here, not yet moved to MDX + +### Migration Status + +The migration from Vite to Next.js is **actively ongoing**. Here's the current state: + +✅ **Completed:** +- Next.js 15 App Router setup +- Internationalization with `next-intl` +- Blog system migrated to MDX +- Main layout and routing structure +- New component architecture in `src/components/` + +🚧 **In Progress:** +- Migrating Vite components to Next.js components +- Converting portfolio project definitions from TypeScript to MDX +- Updating old translation structure +- Removing dependency on legacy directories + +❌ **Not Yet Started:** +- Complete removal of `components-vite/` +- Complete removal of `pages-vite/` +- Full MDX migration for portfolio projects + +### What to Avoid During Migration + +To prevent conflicts, regression, and wasted effort, **DO NOT**: + +#### ❌ Don't Modify Legacy Code +- **Don't edit files in `src/components-vite/`** - These components are being phased out +- **Don't edit files in `src/pages-vite/`** - Page structure has moved to `src/app/[locale]/` +- **Don't add new features to legacy directories** - Build new features in the Next.js structure + +#### ❌ Don't Create Dependencies on Legacy Code +- **Don't import from `components-vite/` in new code** - Use `src/components/` instead +- **Don't reference `pages-vite/` in new routes** - Use App Router pages in `src/app/` +- **Don't expand the legacy translation structure** - Add new content to `src/messages/` or MDX files + +#### ❌ Don't Delete Legacy Code Without Coordination +- **Don't delete legacy directories** - They may still be referenced by unmigrated code +- **Don't remove legacy imports** - Check if they're still in use first +- **Don't assume code is unused** - Verify before removing + +### What You SHOULD Do + +#### ✅ Use the New Architecture +- **Create new components in `src/components/`** - Follow Next.js patterns +- **Add new pages in `src/app/[locale]/`** - Use App Router file conventions +- **Add translations to `src/messages/`** - Use next-intl JSON format +- **Create blog posts as MDX** - Follow the [Adding Blog Posts](#adding-blog-posts) guide + +#### ✅ Reference Legacy Code for Patterns +- **Study `components-vite/` for UI patterns** - Understand the design system, then recreate in new structure +- **Check `pages-vite/` for page logic** - Learn how pages work, then build with App Router +- **Learn from `locales-old/` structure** - Understand content organization before migrating + +#### ✅ Help with Migration (Advanced Contributors) +If you want to help migrate legacy code: +1. **Discuss first** - Open an issue or comment on existing migration issues +2. **Check migration plan** - Ensure your work aligns with the overall strategy +3. **Migrate one component/page at a time** - Small, focused PRs +4. **Test thoroughly** - Ensure migrated code works identically +5. **Update imports** - Fix all references to migrated code +6. **Document changes** - Note what was migrated and any breaking changes + +### Special Case: Portfolio Projects (`locales-old/`) + +**Current State:** Portfolio projects are **still using the legacy structure** in `src/i18n/locales-old/[locale]/portfolio/projects/`. + +**Why:** These TypeScript-based project definitions have not yet been migrated to MDX. + +**What this means for you:** +- ✅ **You can still add portfolio projects** using the TypeScript structure (see [Adding Portfolio Projects](#adding-portfolio-projects)) +- ⚠️ **This structure may change** in the future when projects are migrated to MDX +- 🔄 **Follow existing patterns** - Use the same structure as existing projects + +**Future Plan:** Portfolio projects will eventually be migrated to MDX format (similar to blog posts) for consistency and easier content management. + +### Questions About Legacy Code? + +If you're unsure whether code is legacy or active: +1. **Check the import path** - Legacy code is in `-vite/` or `-old/` directories +2. **Look for usage** - Search the codebase to see if it's imported anywhere +3. **Ask first** - Open an issue or discussion if you're unsure +4. **When in doubt, don't touch it** - Stick to the new architecture in `src/app/`, `src/components/`, and `src/messages/` + ## Commit Guidelines ### Commit Message Format