Pull requests¶

We welcome pull requests for focused fixes and agreed changes. This guide explains how to prepare a contribution we can review and maintain.

Before opening a pull request¶

Please follow these steps before starting your contribution:

1. Search the project's issue tracker. An existing issue may already cover the change. Review its discussion before starting and reference it in your pull request.

2. Choose the right path. Submit small, self-contained fixes directly. Discuss larger bug fixes and change requests with us before starting so we can agree on the scope and approach.

3. Keep security changes private. If your change addresses a potential security vulnerability, follow our security reporting guidance before sharing details or code publicly.

Don't know where to start? Ask the community in our free Discord channel or, if you're a Spark member, in a public Spark space. If the information you need to share may be confidential, use your organization's dedicated private space, if available.

Prepare your contribution¶

Every contribution should meet the following expectations:

• Follow project instructions. Read the contributing guide and run the formatting, linting, testing, and build commands relevant to your change.

• Keep the change focused. Address one problem and include only what is needed. Avoid unrelated refactoring or formatting.

• Use established patterns. Follow the project's existing architecture and conventions. Discuss new approaches and dependencies first, and verify license compatibility.

• Verify the result. Add or update tests and documentation where relevant, then run the applicable checks before submitting.

AI-assisted contributions¶

We welcome contributions made with AI tools. They are reviewed under the same standards as any other contribution, and the same scope rules apply: small, focused fixes may be submitted directly, while larger changes require prior discussion and agreement.

Review and understand the changes you submit, verify that they work, and be prepared to explain and revise them during review. Your DCO sign-off confirms that you have the right to contribute the work under the project's license.

Prepare your commits¶

Prepare each commit as follows:

• Sign each commit with -S. If you haven't configured commit signing, follow GitHub's commit-signing guide. Signed commits appear as verified on GitHub.

• Sign off the contribution with -s. Add a Signed-off-by trailer under the Developer Certificate of Origin to confirm your right to submit the work.

• Confirm co-authors. Before adding a Co-authored-by trailer, obtain each co-author's consent and confirmation that their work complies with the DCO.

• Write a clear commit message. Repositories using our release tooling require the format below. Summaries may appear in release notes, so keep them concise and self-contained.

Use both flags together:

git commit -S -s -m "fix: correct broken navigation (#123)"

Commit summaries use the following format:

<type>: <summary description>

Use exactly one space after the colon, start the summary with lowercase unless the first word is an acronym, and do not end it with punctuation. Do not add a scope such as feature(parser): ..., as our tooling infers it. Add the issue number at the end when the change has a related issue.

• feature – implements a new feature
• fix – fixes a bug
• performance – improves performance
• refactor – improves code without changing behavior
• build – changes the build or CI system
• docs – adds or improves documentation
• style – makes stylistic changes only, such as whitespace
• test – adds or improves tests
• chore – updates tooling or prepares releases

Open the pull request¶

When opening a pull request, provide the following information:

• Summary
• Related issue when required
• Validation
• Checklist

Summary¶

Explain what changed and why it was needed. Include enough context for someone who has not followed the earlier discussion to understand the contribution.

Why we ask: a focused summary helps reviewers understand the intent of the change before examining its implementation.

Related issue when required¶

Link the issue where the scope and approach were agreed. For a small, self-contained fix that did not require prior discussion, briefly explain the problem in the Summary instead.

Why we ask: the issue preserves the decisions and context that led to the contribution, keeping the pull-request discussion focused on the change.

Validation¶

List the automated checks and relevant manual verification you performed. If you could not run an expected check, explain why and note what still needs to be verified.

Why we ask: validation shows which behavior has been checked and helps us focus our review on any remaining risks or unanswered questions.

Checklist¶

Use the checklist for a final review before submitting your pull request. Confirm only completed steps and address anything that is still missing.