You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/copilot-instructions.md
+71-45Lines changed: 71 additions & 45 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,5 @@
1
1
[//]: #"Include this file in the repository to provide instructions to GitHub Copilot Autofix. For more information, see https://docs.github.com/copilot/copilot-for-business/copilot-instructions."
2
+
2
3
# GitHub Copilot instructions
3
4
4
5
This file contains repository-wide guidance for GitHub Copilot. Each top-level
@@ -8,16 +9,17 @@ guidance, etc.).
8
9
9
10
## Agentic autofix for CodeQL Coding Standards
10
11
11
-
This section configures GitHub Copilot (in particular, Copilot **agentic
12
-
autofix**) when it generates pull requests to remediate alerts produced by the
project. It applies to alerts for any of the supported standards (MISRA C,
15
-
MISRA C++, AUTOSAR C++, CERT C, CERT C++).
12
+
This section configures **Agentic Autofix** when generating pull requests to
13
+
remediate alerts produced by [CodeQL Coding Standards](https://github.com/github/codeql-coding-standards/).
14
+
It applies to alerts for any of the supported standards (MISRA C, MISRA C++,
15
+
AUTOSAR C++, CERT C, CERT C++).
16
16
17
17
### 1. Reference material — where to learn each rule
18
18
19
-
Before proposing a fix, consult the rule’s authoritative implementation as well as the corresponding compliant and non-compliant code patterns available as test cases in the CodeQL Coding Standards [`github/codeql-coding-standards`](https://github.com/github/codeql-coding-standards/)
20
-
repository. That repository is the single source of truth for what the query
19
+
Before proposing a fix, consult the rule’s authoritative implementation as well
20
+
as the corresponding compliant and non-compliant code patterns available as
21
+
test cases in the [`github/codeql-coding-standards` repository](https://github.com/github/codeql-coding-standards/).
22
+
That repository is the single source of truth for what the query
21
23
detects and what compliant code looks like.
22
24
23
25
Project layout (per language / standard):
@@ -50,59 +52,83 @@ The full list of supported rules per standard is published as
50
52
-**No drive-by changes.** Do not add features, fix unrelated warnings, change
51
53
build flags, update dependencies, or “improve” code that the alert does not
52
54
point at.
55
+
-**Do not attempt at fixing design issues.** A fix should not attempt to
56
+
“improve” the design of the code or address architectural issues.
57
+
Always verify that the code section around the alert is intended to follow
58
+
the standard and add a comment.
59
+
The presence of certain design issues (e.g. dynamic memory allocation) might
60
+
indicate that the code is not intended to be compliant with the standard, and
61
+
that a deviation should be added instead of a code fix.
53
62
-**New code must comply with the same standard.** Any code introduced by the
54
63
fix must itself satisfy the coding standard being verified (e.g. MISRA C++
55
64
2023). Cross-check the inserted code against the COMPLIANT examples in the
56
65
corresponding `test/rules/<rule-id>/` directory and against neighbouring
57
66
rules that are obviously relevant (e.g. don’t fix an integer-conversion rule
58
67
by introducing a cast that violates a different MISRA rule).
59
-
-**Match the project’s existing style.** Follow the conventions visible in
60
-
the surrounding source files (naming, headers, namespaces, C++ standard
61
-
level, use of `enum class`, etc.).
62
-
-**Preserve behaviour.** A coding-standards fix is a refactor at the source
63
-
level, not a functional change. The fix must not alter observable runtime
64
-
behaviour unless the rule explicitly targets undefined or implementation-
65
-
defined behaviour that has to change.
66
-
67
-
### 3. Do not touch build outputs, generated files, or `.gitignore`
68
-
69
-
Autofix pull requests must only change source files that are part of the
70
-
checked-in project or add deviation records. They must **not** include:
71
-
72
-
- Build directories or files generated during compilation.
73
-
- Editor / IDE state (`.vscode/`, `.idea/`, `.DS_Store`, etc.).
74
-
-**`.gitignore` itself.** Do not add, remove, or reorder entries in
75
-
`.gitignore` as part of an autofix.
76
-
- The CodeQL workflow files under `.github/workflows/` (e.g. `codeql.yml`).
77
-
Suppression or scope changes must use the deviation mechanism (see §4),
78
-
not workflow edits.
79
-
80
-
### 4. Deviations — respect project policy and reference it in fixes
81
-
82
-
A project under analysis may declare that a rule, file, region, or specific
83
-
construct is intentionally exempt from a coding standard. Such deviations are
68
+
-**Preserve safe and desired functional behavior.** ensure the resulting code
69
+
handles all reasonable real-world scenarios as the code originally intended.
70
+
This may involve precisely maintaining the existing code behavior, or it may
71
+
involve fixing subtle or rare bugs, for instance dangerous overflows,
72
+
that the existing code does not handle and the rule is designed to detect.
73
+
-**Fix dangerous bugs** If the alert is flagging unsafe or undefined behavior,
74
+
critically examine how that safety issue in the code should be properly fixed.
75
+
Add detections and error handling if necessary to make the code safe under
76
+
all conditions without introducing unnecessary complexity. Follow existing
77
+
project guidelines on how to handle rare, dangerous, or unexpected scenarios
78
+
that occur at runtime.
79
+
-**Thoroughly explain analysis and functional changes.** If the alert does not
80
+
introduce any unwanted behavior and the change is functionally equivalent,
81
+
explain your thinking, and clearly show that the code before was safe, and
82
+
that the new code is exactly equivalent in behavior.
83
+
If there was a dangerous edge case or condition, explain exactly how that
84
+
scenario would create problems in the code and how the fix will prevent such
85
+
issues and improve the safety and quality of the codebase.
86
+
87
+
### 3. Deviations — respect project policy and reference it in fixes
88
+
89
+
A project may declare that a rule, file, region, or specific construct is
90
+
intentionally exempt from a coding standard. Such deviations are
84
91
not always expressed through the same mechanism: a project may use the
85
-
**standard CodeQL Coding Standards deviation mechanism**, a **custom
86
-
annotation or attribute** convention, **in-source line / block comments**,
92
+
**standard CodeQL Coding Standards deviation mechanism**, a
93
+
**custom annotation or attribute** convention,
94
+
**in-source line / block comments**,
87
95
or a **separate documentation file** (for example a `DEVIATIONS.md`,
88
96
`MISRA-deviations.md`, `coding-standards.yml`, compliance matrix, or similar).
89
97
90
-
The fix proposal must take what is found into account and treat it as an existing deviation if it clearly covers the alert location and rule.
98
+
Locate the deviations file and explicitly search for matching deviations
99
+
before proposing code changes.
100
+
The fix proposal must take what is found into account and treat it as an
101
+
existing deviation if it clearly covers the alert location and rule.
91
102
92
103
If the alert location is covered by an existing deviation:
93
-
94
-
-**Still propose a code fix** that would make the location compliant by
95
-
default. Authors may have left the deviation in place pragmatically and
96
-
may prefer a real fix.
97
-
-**In the pull request description, explicitly state** that a matching
104
+
- Look for existing deviations of that rule, and see if any should apply
105
+
- In the pull request description, explicitly state that a matching
98
106
deviation already exists in the project, citing the file path and the
0 commit comments