diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..091873f8e --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,186 @@ +# 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, + 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 + - [ ] 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 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 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 -- + 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 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. + +## 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. + Try 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 is compatible with the system or other dependencies. +- [ ] Prefer a Semantic Version when applicable.