Skip to content

Commit 3537ce3

Browse files
alexreinkingclaude
alexreinking
and
claude
authored
Add contribution guidelines and issue/PR templates (#8975)
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 11f6bb7 commit 3537ce3

6 files changed

Lines changed: 376 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: Bug report
2+
description: Report a functional correctness problem (wrong output, crash, compilation failure, etc.)
3+
labels: [ "bug" ]
4+
body:
5+
- type: textarea
6+
id: description
7+
attributes:
8+
label: Description
9+
description: >-
10+
A clear and concise description of the bug. What happened and how
11+
did it differ from what you expected? Include error messages or
12+
incorrect output.
13+
validations:
14+
required: true
15+
- type: textarea
16+
id: reproducer
17+
attributes:
18+
label: Reproducing case
19+
description: >-
20+
A minimal, self-contained code example that demonstrates the problem. The
21+
smaller and more self-contained, the better. Ideally, it should look like
22+
one of the tests in `test/correctness`.
23+
render: cpp
24+
validations:
25+
required: true
26+
- type: dropdown
27+
id: halide-source
28+
attributes:
29+
label: How did you get Halide?
30+
options:
31+
- Built from source
32+
- pip (halide)
33+
- vcpkg
34+
- Homebrew
35+
- GitHub release binary
36+
- Other (describe below)
37+
validations:
38+
required: false
39+
- type: input
40+
id: halide-version
41+
attributes:
42+
label: Halide version
43+
description: >-
44+
The version number reported by your package manager, or the release tag
45+
if you downloaded a binary.
46+
placeholder: "e.g. 19.0.0"
47+
validations:
48+
required: false
49+
- type: input
50+
id: halide-commit
51+
attributes:
52+
label: Halide commit (if known)
53+
description: >-
54+
If you built from source, the commit hash you built from.
55+
placeholder: "e.g. abc1234"
56+
validations:
57+
required: false
58+
- type: input
59+
id: target
60+
attributes:
61+
label: Target
62+
description: The Halide target string used when the bug occurs.
63+
placeholder: "e.g. x86-64-linux-avx2, arm-64-osx"
64+
validations:
65+
required: false
66+
- type: input
67+
id: os
68+
attributes:
69+
label: Operating system
70+
placeholder: "e.g. Ubuntu 24.04, macOS 15.3, Windows 11"
71+
validations:
72+
required: false
73+
- type: textarea
74+
id: extra
75+
attributes:
76+
label: Additional context
77+
description: Anything else that might be relevant (build flags, environment, workarounds found, etc.)
78+
validations:
79+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Questions
4+
url: https://github.com/halide/Halide/discussions/categories/q-a
5+
about: Ask questions about using Halide in GitHub Discussions.
6+
- name: Ideas and brainstorming
7+
url: https://github.com/halide/Halide/discussions/categories/ideas
8+
about: >-
9+
Share early-stage ideas or brainstorm in Discussions. Polished proposals
10+
can be promoted to a feature specification issue.
11+
- name: Contributor guidelines
12+
url: https://github.com/halide/Halide/blob/main/CONTRIBUTING.md
13+
about: >-
14+
Guidelines for contributing to Halide development. Read these before
15+
making a pull request or filing an issue.

‎.github/ISSUE_TEMPLATE/enhancement-request.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
name: Enhancement request
2+
description: Report a case where Halide produces a correct output in a suboptimal way
3+
labels: [ "enhancement" ]
4+
body:
5+
- type: textarea
6+
id: description
7+
attributes:
8+
label: Description
9+
description: >-
10+
Describe the problem: could an error message could be made clearer?
11+
Is documentation is missing or misleading?
12+
Was an optimization was missed?
13+
Did a pipeline take unexpectedly long to compile?
14+
validations:
15+
required: true
16+
- type: textarea
17+
id: reproducer
18+
attributes:
19+
label: Reproducing case
20+
description: >-
21+
A minimal, self-contained code example that demonstrates the problem. The
22+
smaller and more self-contained, the better. Ideally, it should look like
23+
one of the tests in `test/correctness`.
24+
render: cpp
25+
validations:
26+
required: true
27+
- type: dropdown
28+
id: halide-source
29+
attributes:
30+
label: How did you get Halide?
31+
options:
32+
- Built from source
33+
- pip (halide)
34+
- vcpkg
35+
- Homebrew
36+
- GitHub release binary
37+
- Other (describe below)
38+
validations:
39+
required: false
40+
- type: input
41+
id: halide-version
42+
attributes:
43+
label: Halide version
44+
description: >-
45+
The version number reported by your package manager, or the release tag
46+
if you downloaded a binary.
47+
placeholder: "e.g. 19.0.0"
48+
validations:
49+
required: false
50+
- type: input
51+
id: halide-commit
52+
attributes:
53+
label: Halide commit (if known)
54+
description: >-
55+
If you built from source, the commit hash you built from.
56+
placeholder: "e.g. abc1234"
57+
validations:
58+
required: false
59+
- type: input
60+
id: target
61+
attributes:
62+
label: Target
63+
description: The Halide target string used when the bug occurs.
64+
placeholder: "e.g. x86-64-linux-avx2, arm-64-osx"
65+
validations:
66+
required: false
67+
- type: input
68+
id: os
69+
attributes:
70+
label: Operating system
71+
placeholder: "e.g. Ubuntu 24.04, macOS 15.3, Windows 11"
72+
validations:
73+
required: false
74+
- type: textarea
75+
id: extra
76+
attributes:
77+
label: Additional context
78+
description: Anything else that might be relevant (build flags, environment, workarounds found, etc.)
79+
validations:
80+
required: false

‎.github/ISSUE_TEMPLATE/feature-spec.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Feature specification
2+
description: >-
3+
Propose a well-specified new feature. For early-stage ideas, please start a
4+
Discussion instead.
5+
labels: [ "feature" ]
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: >-
10+
**Note:** This template is for polished feature proposals. If your idea is
11+
still in the brainstorming stage, please
12+
[start a Discussion](https://github.com/halide/Halide/discussions/categories/ideas)
13+
instead. It can be promoted to an issue once the design solidifies.
14+
- type: textarea
15+
id: problem
16+
attributes:
17+
label: Problem statement
18+
description: What problem does this feature solve? Who is affected?
19+
validations:
20+
required: true
21+
- type: textarea
22+
id: proposal
23+
attributes:
24+
label: Proposed solution
25+
description: >-
26+
Describe the feature in detail. Include proposed API surfaces, semantics,
27+
and behavior. Compare this solution to other approaches you considered.
28+
Why is this one preferred?
29+
validations:
30+
required: true
31+
- type: textarea
32+
id: extra
33+
attributes:
34+
label: Additional context
35+
description: >-
36+
References, related issues, prior art in other projects, or anything
37+
else that supports the proposal.
38+
validations:
39+
required: false

‎.github/pull_request_template.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<!-- Describe your changes and the motivation behind them. -->
2+
3+
Fixes #<!-- issue number, if applicable -->
4+
5+
## Breaking changes
6+
7+
List any breaking changes here. If there are none, you can remove this section.
8+
Common breaking changes include:
9+
10+
- Changes to any existing APIs in the `Halide::` namespace, but not the
11+
`Halide::Internal::` namespace.
12+
- Anything else that may cause existing Halide code to fail to compile or change
13+
output.
14+
15+
These do not necessarily disqualify a PR from being merged, but they should at
16+
least be tagged with the `release_notes` label.
17+
18+
## Checklist
19+
20+
- [ ] Tests added or updated (not required for docs, CI config, or typo fixes)
21+
- [ ] Documentation updated (if public API changed)
22+
- [ ] Python bindings updated (if public API changed)
23+
- [ ] Benchmarks are included here if the change is intended to affect
24+
performance.
25+
- [ ] Commits include AI attribution where applicable (see Code of Conduct)

‎CONTRIBUTING.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Contributing to Halide
2+
3+
Thank you for your interest in contributing to Halide! This document explains
4+
how to participate in the project, whether you're reporting a bug, proposing a
5+
feature, or submitting code.
6+
7+
## Code of Conduct
8+
9+
All participants in the Halide community are expected to follow our
10+
[Code of Conduct](CODE_OF_CONDUCT.md). Please read it before contributing.
11+
12+
## Getting started
13+
14+
### Before opening a pull request
15+
16+
If you are new to the project, please open an Issue or start a Discussion before
17+
submitting a pull request. This helps us align on the approach before you invest
18+
significant effort, and avoids situations where a contribution gets rejected
19+
after the work is already done.
20+
21+
Even for established contributors, opening an Issue or Discussion first is
22+
encouraged for any non-trivial change.
23+
24+
### Questions and brainstorming
25+
26+
For questions about using Halide, brainstorming ideas, or early-stage feature
27+
discussions, please use
28+
[GitHub Discussions](https://github.com/halide/Halide/discussions). Issues are
29+
reserved for actionable items: confirmed bugs, missed optimizations with
30+
reproducing cases, and polished feature specifications.
31+
32+
## Reporting bugs
33+
34+
We have two issue templates for different kinds of problems:
35+
36+
- **Bug report** — for functional correctness issues (wrong output, crashes,
37+
compilation failures, etc.)
38+
- **Enhancement requests** — for cases where Halide produces a correct output,
39+
but something could be better: an error message could be made clearer,
40+
documentation is missing or misleading, an optimization was missed, or a
41+
pipeline took unexpectedly long to compile.
42+
43+
Both templates will ask you to provide a minimal reproducing case. The more
44+
self-contained your example, the faster we can investigate.
45+
46+
## Proposing features
47+
48+
Feature proposals should be well-specified: describe the problem, the proposed
49+
solution, and any alternatives you considered. If your idea is still in the
50+
brainstorming stage, start a Discussion instead; it can be promoted to an issue
51+
once the design solidifies.
52+
53+
## Pull requests
54+
55+
### Requirements
56+
57+
_Note: the following list of requirements is still in an aspirational state. You
58+
may see contributors make ad-hoc, but justified, exceptions to these rules. When
59+
this happens, the justification should be noted in writing in the PR comments._
60+
61+
- **Tests are expected** for all code changes. Bug fixes should include a
62+
regression test. New features should include tests that exercise the new
63+
functionality. We will always ask that new features come with a fuzz test,
64+
where applicable. Documentation-only changes, CI configuration updates, and
65+
trivial fixes (typos, formatting) are exempt.
66+
67+
- **CI must be green.** We merge on green. Our CI runs a number of automated
68+
checks, including (but not limited to) `clang-format` for C++ and `ruff` for
69+
Python. If CI fails, please update your PR to fix the issue. The set of checks
70+
may grow over time. We use `pre-commit` to enforce these checks in CI; it is a
71+
good idea to run it locally, too.
72+
73+
- **AI attribution.** If a significant part of your contribution was generated
74+
by an AI tool, you must note this in the commit message using a
75+
`Co-authored-by` trailer, as described in the
76+
[Code of Conduct](CODE_OF_CONDUCT.md). For example (this list is not
77+
exhaustive):
78+
79+
```
80+
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
81+
Co-authored-by: Cursor <cursoragent@cursor.com>
82+
Co-authored-by: Gemini 3 <gemini-code-assist@google.com>
83+
Co-authored-by: copilot-swe-agent[bot] <198982749+copilot@users.noreply.github.com>
84+
Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>
85+
```
86+
87+
- **Documentation.** New or changed public APIs (those in the `Halide::`
88+
namespace) should be accompanied by updated documentation.
89+
90+
- **Python bindings.** Halide provides a Python binding for its public C++ API.
91+
If your change adds or modifies an API in the `Halide::` namespace, please
92+
update the corresponding Python bindings as well.
93+
94+
- **Performance impact.** If your change could affect code generation quality or
95+
runtime performance, please describe the expected impact in the PR description
96+
and include benchmark results where practical.
97+
98+
### Review and merging
99+
100+
Every pull request requires approval from at least one project maintainer. Once
101+
a PR is approved and CI is green, any maintainer may merge it. While we don't
102+
have a formal code ownership process, it is a good idea to use git-blame to
103+
determine who the relevant maintainer is.
104+
105+
Normally, we are able to review PRs within a (business) week. If a PR has not
106+
been reviewed in that time, please add a comment to the PR tagging the relevant
107+
maintainer. We appreciate reminders, but no more than once per week, please. Do
108+
not ping maintainers over email or other side channels.
109+
110+
If your PR has stalled in review, it may be helpful to break it up into smaller
111+
PRs that are easier to review. A good rule of thumb is that PRs larger than 500
112+
lines take significantly longer to review.
113+
114+
## Common PR anti-patterns
115+
116+
In the past, we have seen PRs fail to be merged for a number of (often
117+
frustrating) reasons. We list a few here to help you avoid them.
118+
119+
1. **Working on something large before broader consensus is reached.** If you're
120+
working on something that you expect to take multiple days of work or
121+
hundreds of lines of code to complete, please start a Discussion to make sure
122+
the design is sound and that the maintainers understand your problem and
123+
agree with your proposed solution. It's frustrating to do a lot of work just
124+
to hear the maintainers think the problem doesn't need to be solved in Halide
125+
(e.g. should be done at the application level or in LLVM). These are
126+
sometimes known as "XY problems."
127+
2. **Communication deadlock between author and reviewer.** We sometimes see PRs
128+
stall because the author and the reviewer believe they are waiting on the
129+
other person to do something. This is why we encourage you to ping PRs when
130+
you're waiting for a response.
131+
3. **Bundling unrelated changes, especially bug-fixes, into a single PR.** When
132+
CI is red due to a pre-existing bug, it is tempting to roll the fix into your
133+
PR. However, this makes the PR larger and makes it take longer to review.
134+
This can snowball.
135+
136+
## Building Halide
137+
138+
See the [README](README.md#building-halide) for build instructions.

0 commit comments

Comments
 (0)