CONTRIBUTING

# Contributing to Vulkan Video Samples

Thank you for your interest in contributing! All contributions should be submitted through pull requests. If you're implementing a new feature, we encourage you to add unit tests using the [testing framework](tests/README.md).

---

## Commit Message Guidelines

All commit messages must follow this format:

```
scope: description
```

### Scope

The scope identifies the area of the codebase being changed:

- **Lowercase** for general areas: `cmake`, `ci`, `docs`, `build`
- **PascalCase** for components: `VkVideoDecoder`, `VkEncoderConfig`, `FindShaderc`
- **Braces** for multiple components: `VkEncoderConfig{H264,H265}`

### Rules

- **Header length**: Maximum 100 characters
- **Subject**: Must not be empty, must not end with a period
- **No draft indicators**: Commits with WIP, fixup, squash, tmp, todo, hack, draft, or similar markers will be rejected

### Examples

```
cmake: fix build issue with shaderc detection
VkVideoDecoder: add support for AV1 profile
docs: update build instructions for Fedora
ci: add commit message validation workflow
```

### Validation

Commit messages are automatically validated on pull requests via commitlint. See `commitlint.config.js` for the full ruleset.

To validate commit messages locally before pushing, install commitlint:

```
npm install --save-dev @commitlint/cli @commitlint/config-conventional
```

Then check the latest commit with:

```
npx commitlint --from=HEAD~1
```
---

## Pull Request Guidelines

When opening a pull request, you'll be presented with a template. Please fill in all required sections.

### PR Title

The PR title must follow the same format as commit messages:

```
scope: description
```

- Same scope rules apply (lowercase for areas, PascalCase for components)
- Maximum 100 characters
- No draft indicators (WIP, fixup, etc.)
- Must not end with a period

### Required Sections

#### Description

Describe your changes clearly. Explain the "why" behind the changes, not just the "what".

#### Type of Change

Specify one of: `bug fix` / `feature` / `refactor` / `docs` / `cleanup`

#### Tests

Every PR must include test results from the [testing framework](tests/README.md). This helps maintainers understand the test coverage and identify potential hardware-specific issues.

**Required format:**

```
### [GPU Model] / [Driver Version] / [OS]

Total Tests: 70
Passed: 48
Failed: 0
Success Rate: 100.0%
```

**Required fields** (validated by CI):
- `Total Tests`
- `Passed`
- `Failed`
- `Success Rate`
- GPU / Driver / OS header line

**Optional fields** (not validated, but recommended):
- `Crashed`
- `Not Supported`
- `Skipped`

This information is essential for tracking codec support across different hardware vendors and driver versions.

### Optional Sections

#### Issue

Link related issues using GitHub keywords:
- `Fixes #123` - closes the issue when PR is merged
- `Related to #456` - references without closing

#### Additional Details

Use this section for any extra context that doesn't fit elsewhere:
- Implementation notes or trade-offs
- Performance considerations
- Migration or upgrade notes
- Screenshots or logs
- Links to related discussions or documentation

### Validation

PR titles and bodies are automatically validated via GitHub Actions. The check will fail if required sections are missing or incorrectly formatted.

### CTS Build Validation

A CI job validates that changes compile correctly within the [VK-GL-CTS](https://github.com/KhronosGroup/VK-GL-CTS) (Vulkan Conformance Test Suite). This ensures integration compatibility before changes reach CTS upstream.

The CTS build runs automatically when the PR title starts with `release:` or when the `cts-build` label is added to a pull request. The job clones VK-GL-CTS, replaces the pinned vulkan-video-samples sources with the PR code, and builds CTS on both Linux (GCC 64-bit Release) and Windows (VS 64-bit Debug).

---

## Release Process

1. Update `Changelog.md` with the new version entry
2. Update the version in `common/include/VkVSCommon.h`
3. Create a PR with `release: create vx.x.x` as title to trigger a CTS build
4. When PR has been merged, create a tag (e.g. `v0.4.0`) on this release commit and push it — GitHub will automatically create a release

---

## Contributor License Agreement

This project welcomes contributions and suggestions. Contributions require you
to agree to a
[Contributor License Agreement (CLA)](https://cla-assistant.io/KhronosGroup/Vulkan-Video-Samples)
declaring that you have the right to, and actually do, grant the rights to use
your contribution.

When you submit a pull request, a CLA bot will determine whether you need to
sign a CLA. Simply follow the instructions provided.

## AI-Assisted Contributions

By submitting a Contribution to this repository, you additionally represent
that, to the extent any of Your Contributions were developed with the
assistance of artificial intelligence tools or AI-generated code, You have
exercised sufficient review, judgment, and creative direction over such tools
and resulting material to reasonably consider it Your original creation, and
You are not aware of any third-party license, intellectual property claim, or
other restriction arising from such use that is associated with any part of
Your Contribution or use thereof.