Contributing

Help build Europe’s digital sovereignty through open silicon.

Quick Start

1. Pick a task: Good first issues
2. Fork repo: Click “Fork” on Codeberg
3. Make changes: Fix bug, add feature, improve docs
4. Submit PR: Create pull request with clear description
5. Review: Respond to feedback, iterate

Ways to Contribute

Code

Hardware (VHDL/Verilog):

• Microwatt core improvements
• A2O bug fixes
• Peripheral development
• Timing optimizations

Software:

• Linux kernel patches
• LiteX integration
• Build system improvements
• Test automation

Difficulty levels:

• 🟢 Good first issue
• 🟡 Moderate complexity
• 🔴 Expert level

See issue tracker for labeled issues.

Documentation

• Fix typos and clarity
• Add examples
• Write tutorials
• Translate (future)

This site: codeberg.org/PowerCommons/documentation

Testing

• Test on different boards
• Report bugs with details
• Verify fixes
• Performance benchmarking

Community

• Answer questions on Matrix
• Help newcomers
• Write blog posts
• Present at conferences

Development Workflow

1. Setup

# Fork on Codeberg, then:
git clone https://codeberg.org/your-username/microwatt-vcu118
cd microwatt-vcu118
git remote add upstream https://codeberg.org/PowerCommons/microwatt-vcu118

2. Create Branch

git checkout -b fix-uart-timing

Branch naming:

• fix/uart-timing - Bug fixes
• feat/ethernet-mac - New features
• docs/build-guide - Documentation

3. Make Changes

# Edit files
vim fpga/uart.vhdl

# Test locally
make test
make synthesize

4. Commit

git add fpga/uart.vhdl
git commit -m "Fix UART timing constraint for 125MHz clock"

Commit message format:

Short summary (50 chars or less)

Detailed explanation if needed. Explain what and why,
not how (code shows how).

Fixes: #123

5. Push and PR

git push origin fix-uart-timing

Open PR on Codeberg with:

• Clear title
• Description of changes
• Related issues
• Test results

Code Standards

VHDL Style

-- Good
signal clk_enable : std_logic;
signal uart_data  : std_logic_vector(7 downto 0);

-- Bad
signal ce : std_logic;  -- unclear name
signal d : std_logic_vector(7 downto 0);  -- too short

Rules:

• Descriptive names
• Comments for complex logic
• Consistent indentation (4 spaces)
• No trailing whitespace

Python (LiteX)

Follow PEP 8:

# Good
def generate_soc(platform, sys_clk_freq):
    """Generate SoC configuration for platform."""
    return BaseSoC(platform, sys_clk_freq=sys_clk_freq)

# Bad
def gen(p,f):
    return BaseSoC(p,sys_clk_freq=f)

Testing

Before Submitting PR

Minimum:

# VHDL syntax check
ghdl -a --std=08 your_file.vhdl

# Python syntax
python3 -m py_compile your_script.py

Recommended:

# Full synthesis test
make synthesize

# Functional simulation
make simulate

# Timing check
make timing-report

Required for hardware changes:

• Test on actual FPGA
• Include resource utilization report
• Verify timing closure

Review Process

What Happens

1. Automated checks: CI runs syntax checks, builds
2. Maintainer review: Code quality, design decisions
3. Discussion: Questions, suggestions, iterations
4. Approval: 1-2 maintainers approve
5. Merge: Changes integrated into main

Timeline: Most PRs reviewed within 48 hours.

Review Criteria

• Correctness: Does it work?
• Quality: Clean, readable code?
• Testing: Adequately tested?
• Documentation: Updated if needed?
• Scope: Focused on one thing?

Communication

Matrix Chat

Real-time discussion: #powercommons:matrix.org

Use for:

• Quick questions
• Design discussions
• Collaboration
• Community chat

Not for:

• Bug reports (use issue tracker)
• Long-form docs (use wiki/PRs)

Issue Tracker

Use Codeberg issues:

Good issue:

Title: UART drops characters at 115200 baud on VCU-118

Description:
When running at 115200 baud, UART occasionally drops
characters. Tested with litex_term.

Steps to reproduce:
1. Program VCU-118 with microwatt.bit
2. Connect: litex_term /dev/ttyUSB1
3. Send large file: cat large.txt > /dev/ttyUSB1
4. Observe missing characters in output

Expected: All characters received
Actual: ~1% dropped

Environment:
- Board: VCU-118
- Bitstream: microwatt-125mhz-20250930
- OS: Debian 12

Bad issue:

Title: UART broken

Description:
Doesn't work. Fix it.

Recognition

Contributors acknowledged in:

• Git commit history
• Release notes
• Project documentation
• Academic papers (if significant contribution)

License

By contributing, you agree:

• Code licensed under project license (Apache 2.0 or GPL-3.0)
• You have rights to contribute
• You grant PowerCommons perpetual license

See LICENSE in each repository.

Code of Conduct

Be respectful, inclusive, collaborative.

Unacceptable:

• Harassment, discrimination
• Trolling, personal attacks
• Spam, off-topic

Enforcement: Warnings, then ban if repeated.

Full text: CODE_OF_CONDUCT.md

Questions

New contributor questions: Matrix #powercommons

Welcome aboard! 🚀