Pull Request Guide

Learn how to create, submit, and get your pull requests merged into the Chapinismos project

This guide walks you through the pull request (PR) process for the Chapinismos project. Following these steps will help your contributions get reviewed and merged quickly.

Before You Start

Before creating a pull request:

1. Read the Getting Started guide
2. Follow the Guidelines for code style and commits
3. Search existing PRs to avoid duplicate work
4. Test your changes locally to ensure everything works

Pull Request Workflow

1. Fork and Clone

If you haven’t already:

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/diccionario-chapin.git
cd diccionario-chapin

2. Create a Feature Branch

Create a descriptive branch name:

# For new features
git checkout -b feature/amazing-feature

# For bug fixes
git checkout -b fix/search-bug

# For adding words
git checkout -b feat/add-word-chilero

Branch naming convention:

• feature/description - New features
• fix/description - Bug fixes
• feat/description - Adding new words or content
• docs/description - Documentation updates

3. Make Your Changes

Work on your changes following the project guidelines:

# Make your changes
# ...

# Format the code
pnpm run format

# Run linter
pnpm run lint

# Test locally
pnpm run dev

# Build to validate
pnpm run build

4. Commit Your Changes

Use Conventional Commits format:

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "feat: agregar palabra 'chilero'"

# For multiple related changes, you can make multiple commits
git commit -m "fix: corregir búsqueda case-sensitive"

5. Push to Your Fork

git push origin feature/amazing-feature

6. Open a Pull Request

1. Go to your fork on GitHub
2. Click “Compare & pull request”
3. Fill out the PR template (see below)
4. Click “Create pull request”

Pull Request Template

When creating a PR, include:

## Description

Brief description of what this PR does.

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] New word(s) added
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Other (please describe):

## Changes Made

- List key changes
- Be specific about what was modified
- Include file paths if relevant

## Screenshots (if applicable)

Add screenshots or GIFs showing the changes

## Testing

Describe how you tested your changes:

- [ ] Tested locally with `pnpm run dev`
- [ ] Build successful with `pnpm run build`
- [ ] No console errors
- [ ] Tested in multiple browsers (if UI change)

## Checklist

See checklist below ⬇️

Pre-Submission Checklist

Before submitting your PR, verify all items:

Code Quality:

• My code follows the project’s style guidelines
• I have formatted the code with pnpm run format
• I have run the linter with pnpm run lint
• No ESLint errors or warnings

Testing:

• I have tested my changes locally with pnpm run dev
• The production build works: pnpm run build
• No errors in the browser console
• Zod validation passes (no schema errors)

Word Entries (if applicable):

• Created both Spanish and English versions
• Both files have the same filename
• Filenames are lowercase, no accents, with hyphens
• All required fields are present
• Examples are natural and contextual
• No offensive or inappropriate content

Documentation:

• Added comments for complex code
• Updated documentation if necessary
• Commit messages are descriptive and follow Conventional Commits

General:

• My changes don’t break existing functionality
• I have reviewed my own code
• No unrelated changes included

What Makes a Good Pull Request?

Clear Title

Use the same format as commit messages:

✅ Good:
- feat: add word 'chilero' with examples and etymology
- fix: resolve case-sensitive search issue
- docs: update contributing guide with commit examples

❌ Bad:
- Update
- Fix stuff
- Changes

Detailed Description

Explain:

• What changes were made
• Why these changes are needed
• How the changes solve the problem

Focused Scope

A good PR:

• ✅ Addresses one specific issue or feature
• ✅ Has related changes only
• ✅ Is easy to review
• ❌ Doesn’t include unrelated changes
• ❌ Isn’t too large or complex

Well Tested

Demonstrate that you’ve tested:

• Local development server works
• Production build succeeds
• No console errors
• Features work as expected

Review Process

What to Expect

1. Initial Review - A maintainer will review within a few days
2. Feedback - Maintainer may request changes or ask questions
3. Updates - Make requested changes and push to the same branch
4. Approval - Once approved, the PR will be merged
5. Merge - Your contribution is live!

Common Review Feedback

Code Style Issues:

# Fix formatting
pnpm run format

# Fix linting issues
pnpm run lint:fix

Missing Tests:

• Ensure you’ve tested locally
• Provide screenshots for UI changes
• Describe test scenarios in PR description

Incomplete Documentation:

• Add code comments for complex logic
• Update relevant documentation
• Ensure commit messages are clear

Responding to Feedback

When a reviewer requests changes:

1. Make the requested changes in your local branch
2. Commit the updates with clear messages:
   git commit -m "fix: address review feedback on search logic"
   
3. Push to the same branch:
   git push origin feature/amazing-feature
   
4. Reply to comments to indicate you’ve addressed them
5. Request re-review if needed

Don’t:

• Force push (unless specifically needed)
• Create a new PR for the same changes
• Get discouraged by feedback - it’s part of the process!
• Make unrelated changes during review

After Your PR is Merged

Celebrate!

Your contribution is now part of Chapinismos! 🎉

Update Your Local Repository

# Switch to main branch
git checkout main

# Add upstream remote (first time only)
git remote add upstream https://github.com/abisai7/diccionario-chapin.git

# Pull latest changes
git pull upstream main

# Delete your feature branch
git branch -d feature/amazing-feature

Recognition

All contributors are recognized:

• Listed in GitHub contributors
• Mentioned in project acknowledgments
• Part of the Chapinismos community!

Troubleshooting

PR Can’t Be Merged (Conflicts)

If your PR has merge conflicts:

# Update your local main branch
git checkout main
git pull upstream main

# Switch back to your feature branch
git checkout feature/amazing-feature

# Merge main into your branch
git merge main

# Resolve conflicts in your editor
# Then commit the merge
git commit -m "merge: resolve conflicts with main"

# Push the updates
git push origin feature/amazing-feature

Build Failing

If the CI build fails:

1. Check the error message in the PR
2. Run pnpm run build locally to reproduce
3. Fix the issue
4. Push the fix to the same branch

Validation Errors

If Zod validation fails:

1. Review the error message - it will tell you what’s wrong
2. Check your word entry frontmatter
3. Ensure all required fields are present and correctly formatted
4. Verify category values are valid
5. Test with pnpm run build

Tips for Faster Review

1. Keep PRs small and focused - Easier to review
2. Write clear descriptions - Explain your changes
3. Follow all guidelines - Reduces back-and-forth
4. Test thoroughly - Catch issues before review
5. Respond promptly to feedback
6. Be patient and respectful - Maintainers are volunteers

Examples of Great PRs

Look at merged PRs in the repository for examples:

• Adding words - Clear, complete entries with both languages
• Bug fixes - Well-described problem and solution
• Features - Documented, tested, and explained

Getting Help

If you’re stuck:

• Comment on your PR with questions
• Open an issue for general questions
• Review existing PRs and issues
• Check the Getting Started guide

---

Thank you for contributing to Chapinismos! Your efforts help preserve and share Guatemalan culture with the world. 🇬🇹