Contribution Workflow

Table of Contents

• Introduction
  • Contributor License Agreement
  • PR Title Convention
• Standard Pull Request Workflow
  • Overview
  • Draft Pull Request
  • Code Review
  • Merge
  • CI/CD Testing
  • Branch Naming
  • Commit Messages
  • Requirements to the Code
  • Providing a Test Case
  • Updating Documentation
• Reporting Issues
• Additional Notes
  • Updating Branches
  • Handling Feedback
  • Related Issues

Introduction

The purpose of this document is to describe the standard workflow for processing contributions to OCCT.

OCCT development is hosted on GitHub at https://github.com/Open-Cascade-SAS/OCCT. All contributions are submitted as Pull Requests (PRs) through the GitHub interface.

Contributor License Agreement

Before contributing, you must sign the Contributor License Agreement (CLA). See the CLA submission form for details.

PR Title Convention

PR titles should follow the pattern <Group> - <Summary>, for example:

Modeling - Modify surface evaluation
Visualization - Fix crash on empty shape display
Data Exchange - Add support for STEP AP242 edition 4

The group identifies the OCCT module or component affected by the change. The summary should be a short, imperative description of what the change does.

Standard Pull Request Workflow

Overview

The contribution workflow follows these steps:

1. Fork and Branch: Fork the OCCT repository and create a feature branch.
2. Develop: Implement the change following Coding Rules.
3. Test: Run existing tests to ensure no regressions. Create a test case when applicable (see Automated Test System).
4. Create Draft PR: Submit a Draft Pull Request on GitHub. CI/CD tests will run automatically.
5. Ready for Review: When the change is complete and CI/CD passes, mark the PR as "Ready for Review".
6. Code Review: A maintainer reviews the change. Feedback is provided as PR comments.
7. Address Feedback: If changes are requested, update the PR. The CI/CD will re-run.
8. Merge: Once approved and all checks pass, the PR is merged.

Draft Pull Request

Start with a Draft PR to signal that the work is in progress. CI/CD pipelines will run on every push, providing early feedback on build and test results.

Create the PR from your fork's feature branch to the IR branch of the official repository.

Code Review

When the Draft PR is ready, mark it as "Ready for Review":

• A reviewer will examine the changes for correctness, compliance with Coding Rules, and completeness.
• Review comments are posted as PR comments. Use GitHub's "Request changes" or "Approve" features.
• Address review feedback by pushing additional commits to the branch. CI/CD re-runs automatically.

Merge

After approval and successful CI/CD checks, the PR is merged by a maintainer. PRs are typically squashed into a single commit on the IR branch.

CI/CD Testing

The following automated checks run on every PR:

• Build on multiple platforms (Windows, Linux, macOS)
• Coding style verification (clang-format)
• DRAW test suite execution

Results are visible in the GitHub Actions tab of the PR.

Branch Naming

There are no restrictions on branch names. Choose a descriptive name that reflects your change (e.g., fix-empty-shape-crash, add-step-ap242-ed4).

Commit Messages

Commit messages should be descriptive. The recommended format:

Modeling - Fix crash in BRepAlgoAPI_Fuse on empty shapes

The commit description should explain:

• Problem: What was wrong
• Change: What was modified and why
• Result: The expected behavior after the fix

Requirements to the Code

The change should comply with OCCT Coding Rules. Re-formatting of unrelated code should be avoided unless done in a dedicated PR.

Providing a Test Case

For functional changes, a test case should be created (unless an existing test already covers it). See Creating a New Test for instructions.

Test data files (CAD models, etc.) should be attached to the GitHub Issue or PR.

Updating Documentation

If the change affects documented functionality, the corresponding documentation in the dox/ directory should be updated in the same PR.

Changes that break API compatibility must be documented in Upgrade from previous OCCT versions.

Reporting Issues

Open issues through the GitHub web interface using the provided issue templates:

• Bug Report - for reproducible defects. The template asks for a description, expected and actual behavior, a sample script or code, OS, compiler, bitness and OCCT version.
• Feature Request - for new functionality or enhancements. The template asks for a description, use case, expected benefits and any additional context.

Templates apply the appropriate labels automatically; there is no need to set them by hand. Maintainers may add further classification labels (component, priority, etc.) during triage.

Additional Notes

Updating Branches

If your branch falls behind IR, rebase it:

git fetch upstream
git rebase upstream/IR

Force-push the updated branch:

git push --force origin <your-branch-name>

Handling Feedback

Review feedback is provided as PR comments. Address each comment by:

• Pushing a fix commit to the same branch
• Replying to the comment thread explaining the resolution
• Resolving the conversation when done

Related Issues

If your PR relates to an existing GitHub issue, use "Closes #123" or "Fixes #456" in the PR description to automatically link and close it on merge.