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.

---

## 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

---

## Developer Certificate of Origin

https://developercertificate.org/

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.