Contributing #

Lightpanda Browser is an open-source project that welcomes contributions from the community. This guide covers everything you need to know to contribute effectively, from signing the Contributor License Agreement to submitting your first pull request.

Prerequisites #

Before contributing, make sure you have a working development environment:

• Zig 0.15.2 installed (see Building from Source for full setup instructions)
• Git for version control
• A GitHub account to submit pull requests
• Familiarity with Lightpanda’s Architecture is recommended for code contributions

Contributor License Agreement (CLA) #

All contributors must sign the Lightpanda Contributor License Agreement before their first contribution can be accepted. The CLA is based on the Apache Software Foundation Contributor License Agreement and protects both you as a contributor and the project.

What the CLA Covers #

The CLA grants Lightpanda (Selecy SAS) a license to use your contributions while you retain all rights to your own work. Specifically:

• Copyright license: A perpetual, worldwide, non-exclusive, royalty-free license to reproduce, prepare derivative works, display, perform, sublicense, and distribute your contributions
• Patent license: A perpetual, worldwide, non-exclusive, royalty-free patent license for claims necessarily infringed by your contributions
• Your rights: You retain all right, title, and interest in your contributions and can use them for any other purpose

How to Sign #

The CLA signing process is automated through CLA Assistant Lite:

1. Open a pull request on the Lightpanda Browser repository
2. The CLA Assistant bot will comment on your PR asking you to sign
3. Reply with the comment: I have read the CLA Document and I hereby sign the CLA
4. The bot records your signature and the check passes

You only need to sign the CLA once. All subsequent pull requests will be automatically approved.

Corporate Contributors #

If you are contributing on behalf of your employer, ensure that:

• You have received permission to make contributions on behalf of your employer, or
• Your employer has waived intellectual property rights for your contributions to Lightpanda

Any individual who makes a contribution from an account associated with a corporate entity is considered authorized to contribute on that entity’s behalf.

Third-Party Work #

If you want to submit work that is not your original creation, submit it separately from your contribution. Include:

• Complete details of the source
• Any license or restriction information (patents, trademarks, license agreements)
• Mark the work clearly as: Submitted on behalf of a third-party: [named here]

Setting Up Your Development Environment #

1. Fork the repository on GitHub
2. Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/browser.git
cd browser

3. Add the upstream remote:

git remote add upstream https://github.com/lightpanda-io/browser.git

4. Install dependencies and build the project (see Building from Source for detailed instructions):

make build-dev

5. Run the test suite to verify your setup:

make test

Making a Contribution #

Step 1: Create a Branch #

Create a feature branch from the latest main:

git fetch upstream
git checkout -b my-feature upstream/main

Step 2: Write Your Code #

Lightpanda is written in Zig. Follow these guidelines:

• Code formatting: All Zig code must pass zig fmt. The CI pipeline runs zig fmt --check on every pull request and will fail if formatting issues are found
• Keep changes focused: Each pull request should address a single concern
• Write tests: Add unit tests for new functionality (see Testing)

Step 3: Run Checks Locally #

Before pushing, run the formatter and tests:

zig fmt --check ./*.zig ./**/*.zig
make test

Step 4: Push and Open a Pull Request #

git push origin my-feature

Then open a pull request on GitHub against the main branch of lightpanda-io/browser.

Pull Request Guidelines #

Writing a Good PR #

• Title: Use a clear, descriptive title summarizing the change
• Description: Explain what the change does and why it is needed
• Link issues: Reference any related GitHub issues
• Small PRs: Smaller, focused pull requests are easier to review and merge

CI Pipeline #

Every pull request triggers several automated checks:

All checks must pass before a pull request can be merged. If a check fails, review the CI logs, fix the issue, and push an update.

Draft Pull Requests #

CI checks are skipped for draft pull requests. Use draft PRs when:

• Your work is still in progress
• You want early feedback on your approach before completing the implementation

Mark your PR as “Ready for review” when all changes are complete.

Code Review #

All contributions go through code review by the Lightpanda maintainers. To facilitate a smooth review:

• Respond to feedback promptly
• Make requested changes in new commits (avoid force-pushing during review)
• Ask questions if feedback is unclear

Licensing #

Lightpanda Browser is licensed under AGPL-3.0-only. By contributing, you agree that your contributions will be licensed under the same terms.

Exceptions #

The following directories are licensed under their original upstream licenses rather than AGPL-3.0:

• vendor/ – third-party vendored dependencies
• tests/wpt/ – Web Platform Tests (upstream test suite)

When contributing code to these directories, be mindful of their respective license requirements.

Types of Contributions #

Bug Reports #

File bug reports as GitHub issues. Include:

• Steps to reproduce the issue
• Expected vs. actual behavior
• Lightpanda version and platform information
• Minimal reproduction case if possible

Feature Requests #

Open a GitHub issue to discuss new features before starting implementation. This helps ensure alignment with the project’s direction and avoids duplicate work.

Code Contributions #

Code contributions can include:

• Bug fixes: Patches for reported issues
• New features: New browser capabilities, CDP domain support, or Web API implementations
• Performance improvements: Optimizations to memory usage, page load time, or throughput
• Test coverage: Additional unit tests, E2E tests, or WPT compliance improvements

Documentation #

Documentation improvements are welcome. This includes fixing typos, clarifying explanations, or adding missing information.

Getting Help #

• GitHub Issues: For bug reports and feature requests
• Pull Request Comments: For discussion about specific changes
• Discord: Join the Lightpanda community for real-time discussion

Next Steps #

• Building from Source – Set up your development environment
• Testing – Learn about the test infrastructure
• Architecture – Understand the codebase structure
• Overview – Project overview and current status