Submitting Merge Requests

​

Before You Start

​

Discuss Large Changes

1. Post to the developer mailing list before you begin substantial work
2. Check if anyone else is working on it
3. Ensure it fits into the overall development plans
4. Get feedback on your approach

​

Start Small

• Starter issues
• Bug fixes
• Small improvements
• Documentation updates

​

General Guidelines

​

1. Use Feature Branches

git checkout -b feature/descriptive-name

• fix/pcbnew-crash-on-export
• feature/add-svg-export
• refactor/simplify-footprint-loading

​

2. Follow Code Style

• Use clang-format for formatting
• Follow naming conventions
• Match the existing code style in files you modify
• Run format checks before submitting

clang-format -i your_modified_file.cpp

​

3. Follow UI Guidelines

• Consistent dialog layouts
• Proper keyboard shortcuts
• Accessibility considerations
• Use wxWidgets sizers appropriately

​

4. Write Good Commit Messages

Add SVG export support to PCB editor

Updated files

Add SVG export support to PCB editor

Implements SVG export with the following features:
- Layer selection dialog
- Configurable stroke width
- Optional drill marks
- Page size options

Fixes #12345

• Use Fixes #123 to automatically close issues
• Use Related to #123 for related issues

​

5. Descriptive Merge Request Titles

• ✅ “Add support for IPC-2581 file import”
• ✅ “Fix crash when exporting Gerber with missing layers”
• ✅ “Refactor symbol library loading for better performance”
• ❌ “Updates”
• ❌ “Fix bug”
• ❌ “Changes to pcbnew”

​

6. Detailed Descriptions

• What changed
• Why it changed
• How to test it
• Screenshots for UI changes
• Related issues or discussions

## Summary

Adds support for importing IPC-2581 format files into the PCB editor.

## Changes

- New IPC2581 parser in `pcbnew/import/`
- Import menu entry and dialog
- Unit tests for parser
- Documentation updates

## Testing

1. Open PCB editor
2. File → Import → IPC-2581
3. Select test file from `qa/data/ipc2581/`
4. Verify layers and components load correctly

## Screenshots

![Import Dialog](screenshot.png)

Fixes #12345

​

GitLab Configuration

​

Configure Your Fork

​

1. Enable CI/CD Visibility

• Set to “Everyone with access”
• This allows reviewers to see your pipeline results

​

2. Set Pipeline Timeout

• Set timeout to 3 hours or longer
• KiCad builds can take time, especially on GitLab shared runners

​

3. Allow Maintainer Commits

• ✅ Check “Allow commits from members who can merge to the target branch” (bottom of MR form)
• This allows maintainers to make minor fixes directly

​

Creating a Merge Request

​

Step 1: Prepare Your Branch

# Ensure you're on your feature branch
git checkout feature/my-feature

# Rebase on latest master
git fetch upstream
git rebase upstream/master

# Run tests
cd build/debug
ctest --output-on-failure

# Format code
clang-format -i path/to/modified/files.cpp

# Commit any formatting fixes
git add .
git commit -m "Apply code formatting"

​

Step 2: Push to Your Fork

git push origin feature/my-feature

git push --force-with-lease origin feature/my-feature

​

Step 3: Create the Merge Request

1. Go to https://gitlab.com/kicad/code/kicad/-/merge_requests/new
2. Select your fork and branch as source
3. Select kicad/code/kicad and master as target
4. Fill in the template:
   • Title
   • Description
   • Related issues
5. ✅ Check “Allow commits from members who can merge to the target branch”
6. Submit

​

CI Pipeline

​

Build Tests

• Linux build
• Windows build
• macOS build (if applicable)

​

Code Quality Checks

• Format check (clang-format)
• Compiler warnings
• Build without errors

​

Unit Tests

• All QA tests must pass
• ctest results are checked

​

What If CI Fails?

​

Format Check Failure

# Apply formatting
clang-format -i modified_files.cpp

# Commit and push
git add .
git commit -m "Apply code formatting"
git push origin feature/my-feature

​

Build Failure

• Check the CI logs for error messages
• Fix the issue locally first
• Test locally before pushing
• Ask for help on the merge request if stuck

​

Test Failure

# Run tests locally
cd build/debug
ctest --output-on-failure

# Fix failing tests
# Commit and push fixes

​

Code Review Process

​

What to Expect

1. Automated checks run immediately (CI pipeline)
2. Maintainer review - A KiCad maintainer will review your code
3. Feedback - You may receive comments and change requests
4. Iteration - Make requested changes and push updates
5. Approval - Once approved, a maintainer will merge your MR

​

Responding to Feedback

• Be responsive to reviewer comments
• Ask questions if you don’t understand feedback
• Make requested changes promptly
• Push updates to the same branch (don’t close and create new MRs)

# Make changes based on feedback
vim file.cpp

# Commit changes
git add file.cpp
git commit -m "Address review feedback: Fix memory leak"

# Push to update MR
git push origin feature/my-feature

​

Resolving Discussions

• Resolve discussions after addressing comments
• Use the “Resolve discussion” button on GitLab
• Add a comment explaining your changes

​

Common Issues and Solutions

​

Merge Conflicts

# Update your local master
git checkout master
git pull upstream master

# Rebase your feature branch
git checkout feature/my-feature
git rebase master

# Resolve conflicts in your editor
# After resolving:
git add resolved_files
git rebase --continue

# Force push (with lease for safety)
git push --force-with-lease origin feature/my-feature

​

Format Check Disagreements

1. Check the Code Style Guide for exceptions
2. Rule 7: Follow existing file formatting when in doubt
3. Comment on the MR explaining why you deviated
4. Maintainers will provide guidance

​

CI Timeout

1. Check your fork’s pipeline timeout setting (should be 3+ hours)
2. Consider splitting large changes into smaller MRs
3. Contact maintainers if issues persist

​

Best Practices

​

Keep Changes Focused

• One feature or fix per merge request
• Don’t mix refactoring with feature changes
• Don’t include unrelated formatting changes

​

Write Tests

// Add unit tests in qa/tests/
TEST_CASE( "My new feature", "[module]" )
{
    // Test code
    REQUIRE( result == expected );
}

​

Update Documentation

• Update relevant documentation
• Add comments to complex code
• Update Doxygen comments

​

Keep Commits Clean

• Maintainers may squash your commits when merging

# Interactive rebase to clean up commits
git rebase -i upstream/master

# Follow prompts to squash/reword commits

​

Test on Multiple Platforms

• Linux
• Windows
• macOS

​

After Your MR is Merged

​

Update Your Local Repository

# Switch to master
git checkout master

# Pull latest changes (including your merged MR)
git pull upstream master

# Push to your fork
git push origin master

# Delete your feature branch (optional)
git branch -d feature/my-feature
git push origin --delete feature/my-feature

​

Celebrate! 🎉

​

Getting Help

• Comment on your MR - Maintainers will respond
• Developer mailing list - https://groups.google.com/a/kicad.org/g/devlist
• Forum - https://forum.kicad.info/
• IRC/Matrix - Check the KiCad website for chat options

​

Additional Resources

• Contributing Guide: https://dev-docs.kicad.org/en/contribute/
• Code Style Guide: https://dev-docs.kicad.org/en/rules-guidelines/code-style/
• UI Guidelines: https://dev-docs.kicad.org/en/rules-guidelines/ui/
• GitLab Docs: https://docs.gitlab.com/ee/user/project/merge_requests/

​

Contributor Recognition

• AUTHORS.txt file in the repository
• KiCad’s About dialog
• Release notes for major contributions