Add copilot-instructions.md

.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.