|
| 1 | +# Copilot instructions for fkYAML |
| 2 | + |
| 3 | +## Project overview |
| 4 | +- This repository contains fkYAML, a header-only C++ YAML library. |
| 5 | +- The library is designed to be portable, dependency-light, and compatible with C++11 and later. |
| 6 | +- Public API changes should preserve existing behavior unless the task explicitly requires otherwise. |
| 7 | + |
| 8 | +## Coding guidelines |
| 9 | +- Prefer small, localized changes that match the existing style of the codebase. |
| 10 | +- Keep the implementation header-only friendly and avoid introducing new external dependencies. |
| 11 | +- Follow the existing naming conventions: |
| 12 | + - namespaces: `fkyaml` and `detail` |
| 13 | + - macros: `FK_YAML_*` |
| 14 | + - functions and variables: snake_case |
| 15 | + - types: descriptive names such as `basic_node`, `node`, `node_type` |
| 16 | + - other conventions: described in the `.clang-format` and `.clang-tidy` files at the root of the repository. |
| 17 | +- Preserve existing namespace and include patterns when editing headers under `include/fkYAML/`. |
| 18 | +- Add the consistent copyright header to new files and maintain it in existing files. |
| 19 | +- Keep comments and documentation concise and useful. |
| 20 | + |
| 21 | +## Build and test |
| 22 | +- The primary build system is CMake. |
| 23 | +- Typical local validation flow: |
| 24 | + 1. `cmake -S . -B build -DFK_YAML_BUILD_TEST=ON` |
| 25 | + 2. `cmake --build build` |
| 26 | + 3. `ctest --test-dir build --output-on-failure` |
| 27 | +- If a change affects parsing, serialization, or node behavior, add or update tests in `tests/unit_test/`. |
| 28 | + |
| 29 | +## Directory structure |
| 30 | +- `/.github/`: GitHub-specific configuration files |
| 31 | + - `/.github/workflows/`: CI/CD workflow definitions |
| 32 | +- `/cmake/`: CMake package configuration and helper files |
| 33 | +- `/docs/`: Documentation files |
| 34 | + - `docs/`: Markdown documentation files |
| 35 | +- `/examples/`: Example usage files (mainly referenced in the documentation) |
| 36 | +- `/include/fkYAML/`: Core headers |
| 37 | + - `*.hpp`: Public headers |
| 38 | + - `detail/`: Implementation headers (not meant to be used directly by users) |
| 39 | + - `*.hpp`: Common headers |
| 40 | + - `conversions/*.hpp`: Conversion functions |
| 41 | + - `encodings/*.hpp`: Encoding/decoding functions |
| 42 | + - `input/*.hpp`: Deserialization functions from YAML to C++ types |
| 43 | + - `macros/*.hpp`: Macro definitions |
| 44 | + - `meta/*.hpp`: Type traits for metaprogramming |
| 45 | + - `output/*.hpp`: Serialization functions from C++ types to YAML |
| 46 | + - `types/*.hpp`: Enum type definitions |
| 47 | +- `/LICENSES/`: license files for the repository dependencies |
| 48 | +- `/scripts/`: Helper scripts for formatting, amalgamation, and repository maintenance |
| 49 | +- `/single_include/fkYAML/`: Amalgamated single-header distribution |
| 50 | +- `/tests/`: Test suite |
| 51 | + - `unit_test/`: Unit tests for all the functionalities of the library |
| 52 | + - `cmake_add_subdirectory_test/`: CMake integration test for add_subdirectory usage |
| 53 | + - `cmake_fetch_content_test/`: CMake integration test for FetchContent usage |
| 54 | + - `cmake_find_package_test/`: CMake integration test for find_package usage |
| 55 | + - `cmake_target_include_directories_test/`: CMake integration test for target_include_directories usage |
| 56 | +- `/thirdparty/`: Vendored dependencies (for testing and CI workflows, not part of the public API) |
| 57 | +- `/tools/`: Maintenance and benchmarking utilities |
| 58 | + |
| 59 | +## Directory-specific guidance |
| 60 | +- `include/fkYAML/`: treat public headers as the stable API surface; prefer backward-compatible changes. |
| 61 | +- `include/fkYAML/detail/`: keep internal implementation headers consistent and avoid exposing unnecessary details. |
| 62 | +- `single_include/fkYAML/`: keep the amalgamated single-header distribution aligned with changes in the main headers; regenerate it when necessary. |
| 63 | +- `tests/`: keep the test suite organized and ensure changes are 100% covered by appropriate tests when there is any change in the codebase. |
| 64 | +- `thirdparty/`: avoid modifying vendored dependencies unless the task explicitly requires it. |
| 65 | +- `examples/`: keep examples simple, buildable, and consistent with the documented usage. |
| 66 | +- `docs/`: update documentation when public behavior or APIs change. |
| 67 | +- `tools/`: keep maintenance and benchmarking utilities compatible with the existing workflows. |
| 68 | +- `scripts/`: preserve helper scripts for formatting, amalgamation, and repository maintenance. |
| 69 | +- `cmake/`: keep package configuration and CMake helper files consistent with build changes. |
| 70 | +- `build/`: generated build output; do not edit manually. |
| 71 | + |
| 72 | +## Compatibility and safety |
| 73 | +- Avoid breaking older compilers or C++11 compatibility. |
| 74 | +- Do not introduce C++14/17-only constructs unless the task explicitly requires them and the repository already supports them. |
| 75 | +- If a change affects the public API, consider updating related documentation and examples. |
| 76 | +- Respect the repository license headers and existing REUSE metadata. |
0 commit comments