damjan_savic/Portfolio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

auto-claude: subtask-1-5 - Document branch/PR conventions and legacy code

Browse Source 
Added comprehensive documentation for:
- Branch naming conventions with patterns and examples
- Pull request guidelines including pre-submission checklist, PR template, and best practices
- Legacy code explanation for components-vite, pages-vite, and locales-old directories
- Migration status and what to avoid touching during Vite to Next.js migration
- Updated table of contents with new sections

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
damjan_savic
2026-01-25 06:39:49 +01:00
co-authored by Claude Sonnet 4.5
parent 65f3a28435
commit 7fde675ee0
1 changed files with 269 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+269
View File
@@ -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/<description>` | `feature/add-dark-mode` | New features or enhancements |
| **Bug Fix** | `fix/<description>` | `fix/mobile-nav-bug` | Bug fixes and error corrections |
| **Documentation** | `docs/<description>` | `docs/update-readme` | Documentation updates |
| **Refactoring** | `refactor/<description>` | `refactor/contact-form` | Code restructuring without behavior changes |
| **Testing** | `test/<description>` | `test/add-unit-tests` | Adding or updating tests |
| **Chore** | `chore/<description>` | `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:
```
<type>: <brief description>
```
**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