From 4440428ffb2a007aff992296a616305dbfceff14 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Wed, 14 Jan 2026 15:40:33 +0000 Subject: [PATCH 1/3] Add copilot-instructions.md To guide the work of copilot See: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions --- .github/copilot-instructions.md | 185 ++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..928a69a63 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,185 @@ +# Instructions + +## Project contribution guidelines + +- [ ] Follow the project's established coding style and conventions. +- [ ] Run Ruff and fix errors before committing code. + - [ ] New code should be written to pass all Ruff checks. + - [ ] McCabe complexity should be kept low; refactor the new code + that exceeds 10. + - [ ] Existing code should be gradually improved to pass Ruff checks + when making changes. +- [ ] Write clear and concise commit messages that accurately describe + the changes made. +- [ ] For significant changes, update the CHANGELOG.md file + to document the changes. + - [ ] Follow "Keep a Changelog" principles + https://keepachangelog.com/en/1.0.0/ + - [ ] Use semantic versioning for version numbers + https://semver.org/ + - [ ] If it is a breaking change, indicate it clearly in the changelog. + - [ ] Provide migration instructions if necessary. +- [ ] Do not leave trailing whitespaces in the code or documentation files. +- [ ] Metadata in pyproject.toml, codemeta.json, CITATION.cff, and other + project metadata files should be consistent and up-to-date. + - [ ] Project name + - [ ] Project version + - [ ] Author/contributor names + - [ ] License information + - [ ] Project description + - [ ] Repository URL + - [ ] Keywords/tags (in the same order if possible) +- [ ] requires-python in pyproject.toml should reflect the minimum + Python version supported by the project. + - [ ] Do not introduce syntax or features that are not supported + by the specified minimum Python version, + unless it is supported via __future__ imports. + +## General language use + +- [ ] Write short and simple comments. Do not state the obvious. +- [ ] Prefer clear, concise, and unambiguous sentences. +- [ ] Do not use jargon, slang, or idiomatic expressions + that may not be universally understood. +- [ ] Use active voice whenever possible. +- [ ] Use consistent terminology throughout the code and documentation. +- [ ] Define acronyms and abbreviations on their first use. +- [ ] Use technical terms accurately and appropriately. +- [ ] Avoid unnecessary complexity and verbosity. +- [ ] Use proper grammar, punctuation, and spelling. +- [ ] Use consistent formatting for dates, times, numbers, and units of measure. +- [ ] When using abbreviations for units of measure, follow the International + System of Units (SI) conventions. +- [ ] When using code snippets, ensure they are properly formatted and + follow the conventions of the programming language being used. +- [ ] Avoid words and phrases that may have more than one interpretation. +- [ ] Avoid overly long paragraphs. Breaking up text into smaller paragraphs, + using bullet points, or creating numbered lists to improve readability. +- [ ] Help reader's comprehension by separating distinct concepts, processes, + criteria, or categories. +- [ ] Use parallel language structures in lists and documentation. +- [ ] Use a uniform writing style, particularly when presenting similar or + related information, so the reader's compare easily. +- [ ] If not specified otherwise, use Chicago style for reference/citation. +- [ ] When writing on level of requirements, use the verbal forms consistently. + Use either ISO/IEC verbal form (ISO/IEC Directives, Part 2 -- + Principles and rules for the structure and drafting of ISO and IEC + documents) or IETF verbal form (RFC 2119 and RFC 8174). + Try to detect the level of requirements from type/domain of the document. + IETF is default for internet/web/semantic web projects in general. + ISO is default for SPDX project. +- [ ] Use American English spelling consistently. + +## Naming conventions + +- [ ] Follow standard naming conventions for the programming language + and framework you are using. +- [ ] Use only ASCII letters, digits, hyphen (-), and underscore (_) + in names. +- [ ] For URLs/IRIs, use lowercase letters and hyphens to separate words + (e.g., `my-api-endpoint`) and follow W3C Cool URIs for the Semantic Web: + https://www.w3.org/TR/cooluris/ +- [ ] Consult Schema.org vocabularies when deciding about names. +- [ ] Consult "Style Guidelines for Naming and Labeling Ontologies in the + Multilingual Web" https://www.researchgate.net/publication/277224472 + +## Tidy code and documentation + +- [ ] Ensure that the code is well-formatted and adheres to the style + guidelines of the programming language you are using. +- [ ] Use linters and formatters where applicable. +- [ ] Use "sentence case" for headings and titles in documentation. +- [ ] Write clear and concise comments and documentation for your code. + For something obvious, avoid comments that just restate the code. +- [ ] After making changes, review the code and documentation to ensure + up-to-dateness, correctness, consistency, and clarity. +- [ ] Make sure that all code comments, APIs, and documentation are consistent + with the current state of the codebase. +- [ ] Make sure that the examples in the documentation are runnable, up-to-date + and reflect the current behavior of the code. + +## File header + +- [ ] When possible, put relevant SPDX File Tags at file header. + See https://spdx.github.io/spdx-spec/v2.3/file-information/ + - [ ] SPDX-FileContributor + - [ ] SPDX-FileCopyrightText + - [ ] Default SPDX-FileType for code is "SOURCE" + - [ ] Default SPDX-FileType for documentation is "DOCUMENTATION" + - [ ] Default SPDX-License-Identifier for code is "Apache-2.0" + - [ ] Default SPDX-License-Identifier for documentation is "CC0-1.0" + - [ ] Sort SPDX metadata. + +## Shell scripts and command line + +- [ ] Mind the differences between GNU, BSD, macOS, + and other implementations of common Unix tools. +- [ ] Be defensive on variable expansion. +- [ ] Use quotes or other constructs to encapsulate paths, make it compatible + with different kinds of shells. +- [ ] Be mindful about semantic of different types of quotation marks. + +## Library imports and dependencies + +- [ ] Recheck the correctness of library/module/package name. + Be very careful of slopsquatting and typosquatting attacks. +- [ ] Use the most updated version of the library that is supported + by the OS/compiler/framework currently being in used. +- [ ] In source code, sort imports by the programming language convention + and then by alphabetical order whenever possible. + Be careful of specific order of import requirements of some dependencies. +- [ ] In build metadata (like pyproject.toml in Python) or + dependency list (like requirements.txt in Python), sort dependencies. +- [ ] Warn users about abandoned dependency with no maintenance + for long time and suggest equivalent drop-in replacement. + +## API + +- [ ] The over architecture, code, API endpoints to follow the latest version + of OpenAPI specification at https://spec.openapis.org/oas/ +- [ ] API endpoints must use proper HTTP return code +- [ ] Follows web best practices as recommended by OpenAPI, IETF, W3C, etc. + +## JSON + +- [ ] When serialize to JSON, always enclose decimal values + (for example, xs:decimal) in quotes to guarantee correct type + interpretation and preserve precision. +- [ ] Make sure JSON is valid and well-formatted. + +## Markdown + +- [ ] When including metadata in Markdown file, + put them as YAML between triple-dashed lines, + as used by Hugo and Jekyll front matter. +- [ ] Be strict on the Markdown formatting. + Be mindful that what works on GitHub may not work on MkDocs, for example. + Ty to keep with the standard Markdown. +- [ ] Use Markdownlint to detect and fix malformatted. + +## Diagram + +- [ ] When draw the diagram in ASCII/text, recheck if all the lines are well + aligned. + Count the characters and adjust the spaces so the lines align well. + +## HTML + +- [ ] Make sure HTML is valid and well-formatted. +- [ ] Make sure there is no trailing whitespace in the HTML file. +- [ ] Be conscious about accessibility. Consider to follow W3C web + accessibility recommendations when possible. +- [ ] Use sensible and concise element IDs and names that allow code + readability, name grouping also helps. + +## CSS + +- [ ] Make sure there is no unused styles. +- [ ] Use sensible and concise element IDs and names that allow code + readability, name grouping also helps. + +## Version + +- [ ] When suggest dependencies, recheck the version; if the version exists, + or if the version compatible with the system or other dependencies. +- [ ] When manage own's project, prefer a Semantic Version. From 0992e516030d9b598c1d41bd17c017939ff5cd4b Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Wed, 14 Jan 2026 15:50:32 +0000 Subject: [PATCH 2/3] Update trailing whitespace guideline for clarity Clarify the guideline about trailing whitespaces in code and documentation files. --- .github/copilot-instructions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 928a69a63..93cb9a7ea 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -19,7 +19,8 @@ https://semver.org/ - [ ] If it is a breaking change, indicate it clearly in the changelog. - [ ] Provide migration instructions if necessary. -- [ ] Do not leave trailing whitespaces in the code or documentation files. +- [ ] Do not leave trailing whitespaces in the code or documentation files, + unless it is explicitly necessary to such a whitespace. - [ ] Metadata in pyproject.toml, codemeta.json, CITATION.cff, and other project metadata files should be consistent and up-to-date. - [ ] Project name From 776a74fe3463ec1beabb3bf3fb26f082b396a438 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Wed, 14 Jan 2026 16:50:36 +0000 Subject: [PATCH 3/3] Fix grammar issues --- .github/copilot-instructions.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 93cb9a7ea..091873f8e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -20,7 +20,7 @@ - [ ] If it is a breaking change, indicate it clearly in the changelog. - [ ] Provide migration instructions if necessary. - [ ] Do not leave trailing whitespaces in the code or documentation files, - unless it is explicitly necessary to such a whitespace. + unless such a whitespace is explicitly necessary. - [ ] Metadata in pyproject.toml, codemeta.json, CITATION.cff, and other project metadata files should be consistent and up-to-date. - [ ] Project name @@ -56,11 +56,11 @@ - [ ] Avoid words and phrases that may have more than one interpretation. - [ ] Avoid overly long paragraphs. Breaking up text into smaller paragraphs, using bullet points, or creating numbered lists to improve readability. -- [ ] Help reader's comprehension by separating distinct concepts, processes, +- [ ] Help readers' comprehension by separating distinct concepts, processes, criteria, or categories. - [ ] Use parallel language structures in lists and documentation. - [ ] Use a uniform writing style, particularly when presenting similar or - related information, so the reader's compare easily. + related information, so the reader can compare easily. - [ ] If not specified otherwise, use Chicago style for reference/citation. - [ ] When writing on level of requirements, use the verbal forms consistently. Use either ISO/IEC verbal form (ISO/IEC Directives, Part 2 -- @@ -136,8 +136,8 @@ ## API -- [ ] The over architecture, code, API endpoints to follow the latest version - of OpenAPI specification at https://spec.openapis.org/oas/ +- [ ] The overall architecture, code, API endpoints to follow the latest + version of OpenAPI specification at https://spec.openapis.org/oas/ - [ ] API endpoints must use proper HTTP return code - [ ] Follows web best practices as recommended by OpenAPI, IETF, W3C, etc. @@ -155,7 +155,7 @@ as used by Hugo and Jekyll front matter. - [ ] Be strict on the Markdown formatting. Be mindful that what works on GitHub may not work on MkDocs, for example. - Ty to keep with the standard Markdown. + Try to keep with the standard Markdown. - [ ] Use Markdownlint to detect and fix malformatted. ## Diagram @@ -182,5 +182,5 @@ ## Version - [ ] When suggest dependencies, recheck the version; if the version exists, - or if the version compatible with the system or other dependencies. -- [ ] When manage own's project, prefer a Semantic Version. + or if the version is compatible with the system or other dependencies. +- [ ] Prefer a Semantic Version when applicable.