Skip to content

Commit 1328e91

Browse files
bactbact
authored
Merge pull request #1198 from bact/add-copilot-instructions
Add copilot-instructions.md
2 parents 6550a5f + 776a74f commit 1328e91

1 file changed

Lines changed: 186 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Instructions
2+
3+
## Project contribution guidelines
4+
5+
- [ ] Follow the project's established coding style and conventions.
6+
- [ ] Run Ruff and fix errors before committing code.
7+
- [ ] New code should be written to pass all Ruff checks.
8+
- [ ] McCabe complexity should be kept low; refactor the new code
9+
that exceeds 10.
10+
- [ ] Existing code should be gradually improved to pass Ruff checks
11+
when making changes.
12+
- [ ] Write clear and concise commit messages that accurately describe
13+
the changes made.
14+
- [ ] For significant changes, update the CHANGELOG.md file
15+
to document the changes.
16+
- [ ] Follow "Keep a Changelog" principles
17+
https://keepachangelog.com/en/1.0.0/
18+
- [ ] Use semantic versioning for version numbers
19+
https://semver.org/
20+
- [ ] If it is a breaking change, indicate it clearly in the changelog.
21+
- [ ] Provide migration instructions if necessary.
22+
- [ ] Do not leave trailing whitespaces in the code or documentation files,
23+
unless such a whitespace is explicitly necessary.
24+
- [ ] Metadata in pyproject.toml, codemeta.json, CITATION.cff, and other
25+
project metadata files should be consistent and up-to-date.
26+
- [ ] Project name
27+
- [ ] Project version
28+
- [ ] Author/contributor names
29+
- [ ] License information
30+
- [ ] Project description
31+
- [ ] Repository URL
32+
- [ ] Keywords/tags (in the same order if possible)
33+
- [ ] requires-python in pyproject.toml should reflect the minimum
34+
Python version supported by the project.
35+
- [ ] Do not introduce syntax or features that are not supported
36+
by the specified minimum Python version,
37+
unless it is supported via __future__ imports.
38+
39+
## General language use
40+
41+
- [ ] Write short and simple comments. Do not state the obvious.
42+
- [ ] Prefer clear, concise, and unambiguous sentences.
43+
- [ ] Do not use jargon, slang, or idiomatic expressions
44+
that may not be universally understood.
45+
- [ ] Use active voice whenever possible.
46+
- [ ] Use consistent terminology throughout the code and documentation.
47+
- [ ] Define acronyms and abbreviations on their first use.
48+
- [ ] Use technical terms accurately and appropriately.
49+
- [ ] Avoid unnecessary complexity and verbosity.
50+
- [ ] Use proper grammar, punctuation, and spelling.
51+
- [ ] Use consistent formatting for dates, times, numbers, and units of measure.
52+
- [ ] When using abbreviations for units of measure, follow the International
53+
System of Units (SI) conventions.
54+
- [ ] When using code snippets, ensure they are properly formatted and
55+
follow the conventions of the programming language being used.
56+
- [ ] Avoid words and phrases that may have more than one interpretation.
57+
- [ ] Avoid overly long paragraphs. Breaking up text into smaller paragraphs,
58+
using bullet points, or creating numbered lists to improve readability.
59+
- [ ] Help readers' comprehension by separating distinct concepts, processes,
60+
criteria, or categories.
61+
- [ ] Use parallel language structures in lists and documentation.
62+
- [ ] Use a uniform writing style, particularly when presenting similar or
63+
related information, so the reader can compare easily.
64+
- [ ] If not specified otherwise, use Chicago style for reference/citation.
65+
- [ ] When writing on level of requirements, use the verbal forms consistently.
66+
Use either ISO/IEC verbal form (ISO/IEC Directives, Part 2 --
67+
Principles and rules for the structure and drafting of ISO and IEC
68+
documents) or IETF verbal form (RFC 2119 and RFC 8174).
69+
Try to detect the level of requirements from type/domain of the document.
70+
IETF is default for internet/web/semantic web projects in general.
71+
ISO is default for SPDX project.
72+
- [ ] Use American English spelling consistently.
73+
74+
## Naming conventions
75+
76+
- [ ] Follow standard naming conventions for the programming language
77+
and framework you are using.
78+
- [ ] Use only ASCII letters, digits, hyphen (-), and underscore (_)
79+
in names.
80+
- [ ] For URLs/IRIs, use lowercase letters and hyphens to separate words
81+
(e.g., `my-api-endpoint`) and follow W3C Cool URIs for the Semantic Web:
82+
https://www.w3.org/TR/cooluris/
83+
- [ ] Consult Schema.org vocabularies when deciding about names.
84+
- [ ] Consult "Style Guidelines for Naming and Labeling Ontologies in the
85+
Multilingual Web" https://www.researchgate.net/publication/277224472
86+
87+
## Tidy code and documentation
88+
89+
- [ ] Ensure that the code is well-formatted and adheres to the style
90+
guidelines of the programming language you are using.
91+
- [ ] Use linters and formatters where applicable.
92+
- [ ] Use "sentence case" for headings and titles in documentation.
93+
- [ ] Write clear and concise comments and documentation for your code.
94+
For something obvious, avoid comments that just restate the code.
95+
- [ ] After making changes, review the code and documentation to ensure
96+
up-to-dateness, correctness, consistency, and clarity.
97+
- [ ] Make sure that all code comments, APIs, and documentation are consistent
98+
with the current state of the codebase.
99+
- [ ] Make sure that the examples in the documentation are runnable, up-to-date
100+
and reflect the current behavior of the code.
101+
102+
## File header
103+
104+
- [ ] When possible, put relevant SPDX File Tags at file header.
105+
See https://spdx.github.io/spdx-spec/v2.3/file-information/
106+
- [ ] SPDX-FileContributor
107+
- [ ] SPDX-FileCopyrightText
108+
- [ ] Default SPDX-FileType for code is "SOURCE"
109+
- [ ] Default SPDX-FileType for documentation is "DOCUMENTATION"
110+
- [ ] Default SPDX-License-Identifier for code is "Apache-2.0"
111+
- [ ] Default SPDX-License-Identifier for documentation is "CC0-1.0"
112+
- [ ] Sort SPDX metadata.
113+
114+
## Shell scripts and command line
115+
116+
- [ ] Mind the differences between GNU, BSD, macOS,
117+
and other implementations of common Unix tools.
118+
- [ ] Be defensive on variable expansion.
119+
- [ ] Use quotes or other constructs to encapsulate paths, make it compatible
120+
with different kinds of shells.
121+
- [ ] Be mindful about semantic of different types of quotation marks.
122+
123+
## Library imports and dependencies
124+
125+
- [ ] Recheck the correctness of library/module/package name.
126+
Be very careful of slopsquatting and typosquatting attacks.
127+
- [ ] Use the most updated version of the library that is supported
128+
by the OS/compiler/framework currently being in used.
129+
- [ ] In source code, sort imports by the programming language convention
130+
and then by alphabetical order whenever possible.
131+
Be careful of specific order of import requirements of some dependencies.
132+
- [ ] In build metadata (like pyproject.toml in Python) or
133+
dependency list (like requirements.txt in Python), sort dependencies.
134+
- [ ] Warn users about abandoned dependency with no maintenance
135+
for long time and suggest equivalent drop-in replacement.
136+
137+
## API
138+
139+
- [ ] The overall architecture, code, API endpoints to follow the latest
140+
version of OpenAPI specification at https://spec.openapis.org/oas/
141+
- [ ] API endpoints must use proper HTTP return code
142+
- [ ] Follows web best practices as recommended by OpenAPI, IETF, W3C, etc.
143+
144+
## JSON
145+
146+
- [ ] When serialize to JSON, always enclose decimal values
147+
(for example, xs:decimal) in quotes to guarantee correct type
148+
interpretation and preserve precision.
149+
- [ ] Make sure JSON is valid and well-formatted.
150+
151+
## Markdown
152+
153+
- [ ] When including metadata in Markdown file,
154+
put them as YAML between triple-dashed lines,
155+
as used by Hugo and Jekyll front matter.
156+
- [ ] Be strict on the Markdown formatting.
157+
Be mindful that what works on GitHub may not work on MkDocs, for example.
158+
Try to keep with the standard Markdown.
159+
- [ ] Use Markdownlint to detect and fix malformatted.
160+
161+
## Diagram
162+
163+
- [ ] When draw the diagram in ASCII/text, recheck if all the lines are well
164+
aligned.
165+
Count the characters and adjust the spaces so the lines align well.
166+
167+
## HTML
168+
169+
- [ ] Make sure HTML is valid and well-formatted.
170+
- [ ] Make sure there is no trailing whitespace in the HTML file.
171+
- [ ] Be conscious about accessibility. Consider to follow W3C web
172+
accessibility recommendations when possible.
173+
- [ ] Use sensible and concise element IDs and names that allow code
174+
readability, name grouping also helps.
175+
176+
## CSS
177+
178+
- [ ] Make sure there is no unused styles.
179+
- [ ] Use sensible and concise element IDs and names that allow code
180+
readability, name grouping also helps.
181+
182+
## Version
183+
184+
- [ ] When suggest dependencies, recheck the version; if the version exists,
185+
or if the version is compatible with the system or other dependencies.
186+
- [ ] Prefer a Semantic Version when applicable.

0 commit comments

Comments
 (0)