diff --git a/.devcontainer/codespace.code-workspace b/.devcontainer/codespace.code-workspace new file mode 100644 index 000000000..e157bc5c3 --- /dev/null +++ b/.devcontainer/codespace.code-workspace @@ -0,0 +1,119 @@ +{ + "folders": [ + { + "name": "Phlex", + "path": "/workspaces/phlex" + }, + { + "name": "Phlex Design", + "path": "/workspaces/phlex-design" + }, + { + "name": "Phlex Examples", + "path": "/workspaces/phlex-examples" + }, + { + "name": "Phlex Coding Guidelines", + "path": "/workspaces/phlex-coding-guidelines" + }, + { + "name": "Phlex Spack Recipes", + "path": "/workspaces/phlex-spack-recipes" + } + ], + "settings": { + "files.associations": { + "*.yml": "yaml", + "*.yaml": "yaml" + }, + "files.exclude": { + "**/local/.*/**": true, + "**/local/*/": true + }, + "search.exclude": { + "**/local/.*/**": true, + "**/local/*/": true, + "**/build/_deps/**": true, + "**/build/CMakeFiles/**": true + }, + "files.watcherExclude": { + "**/local/.*/**": true, + "**/local/*/": true, + "**/build/_deps/**": true, + "**/build/CMakeFiles/**": true + }, + "cmake.sourceDirectory": "${workspaceFolder:Phlex}", + "cmake.buildDirectory": "${workspaceFolder:Phlex}/build", + "cmake.useCMakePresets": "always", + "cmake.generator": "Ninja", + "C_Cpp.default.cStandard": "c17", + "C_Cpp.default.cppStandard": "c++23", + "C_Cpp.default.intelliSenseMode": "linux-gcc-x64", + "C_Cpp.default.compileCommands": "${workspaceFolder:Phlex}/build/compile_commands.json", + "C_Cpp.exclusionPolicy": "checkFolders", + "C_Cpp.files.exclude": { + "**/local/.*/**": true, + "**/local/*/": true, + "**/build/_deps/**": true, + "**/build/CMakeFiles/**": true + }, + "python.languageServer": "Pylance", + "python.analysis.typeCheckingMode": "basic", + "python.analysis.diagnosticMode": "workspace", + "python.analysis.exclude": [ + "**/local/.*/**", + "**/local/*/", + "**/build/_deps/**", + "**/build/CMakeFiles/**" + ], + "python.analysis.ignore": [ + "**/local/.*/**", + "**/local/*/", + "**/build/_deps/**", + "**/build/CMakeFiles/**" + ], + "flake8.enabled": false, + "[python]": { + "editor.formatOnSave": true, + "editor.defaultFormatter": "charliermarsh.ruff", + "editor.codeActionsOnSave": { + "source.organizeImports.ruff": "explicit", + "source.fixAll.ruff": "explicit" + } + }, + "yaml.schemas": { + "https://json.schemastore.org/github-workflow.json": "./.github/workflows/*" + } + }, + "extensions": { + "recommendations": [ + "ms-vscode.cmake-tools", + "ms-vscode.cpptools", + "ms-vscode.cpptools-extension-pack", + "twxs.cmake", + "ms-vscode.vscode-json", + "redhat.vscode-yaml", + "charliermarsh.ruff", + "github.vscode-github-actions", + "github.copilot", + "github.copilot-chat", + "github.vscode-pull-request-github", + "ms-vscode.hexeditor" + ], + "unwantedRecommendations": [ + "reditorsupport.r", + "ms-vscode.r", + "ikuyadeu.r", + "ms-vscode.r-debugger", + "vscjava.vscode-java-pack", + "redhat.java", + "vscjava.vscode-java-debug", + "vscjava.vscode-java-test", + "vscjava.vscode-maven", + "vscjava.vscode-gradle", + "ms-python.python", + "ms-toolsai.jupyter", + "ms-python.flake8" + ] + } +} diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 7d8cf8ae3..899513d40 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -14,6 +14,7 @@ "mounts": [ "source=${env:HOME}/.config/gh,target=/home/vscode/.config/gh,type=bind,readonly" ], + "onCreateCommand": "bash .devcontainer/setup-repos.sh /workspaces", "customizations": { "vscode": { "settings": { @@ -38,7 +39,7 @@ "cmake.ctestPath": "${workspaceFolder}/.devcontainer/ctest_wrapper.sh", "cmake.generator": "Ninja", "C_Cpp.default.cStandard": "c17", - "C_Cpp.default.cppStandard": "c++20", + "C_Cpp.default.cppStandard": "c++23", "C_Cpp.default.intelliSenseMode": "linux-gcc-x64", "C_Cpp.default.compileCommands": "${workspaceFolder}/build/compile_commands.json", "python.languageServer": "Pylance", diff --git a/.devcontainer/setup-repos.sh b/.devcontainer/setup-repos.sh new file mode 100755 index 000000000..ec618b731 --- /dev/null +++ b/.devcontainer/setup-repos.sh @@ -0,0 +1,44 @@ +#!/bin/bash + +# Clone companion repositories into the codespace so they are available +# for reference by developers and AI agents. +# +# Intended to be called from devcontainer.json onCreateCommand. + +set -euo pipefail + +WORKSPACE_ROOT="${1:-/workspaces}" + +if [ ! -d "$WORKSPACE_ROOT" ]; then + echo "Error: workspace root does not exist: $WORKSPACE_ROOT" >&2 + exit 1 +fi + +clone_if_absent() { + local repo=$1 + local dest="${WORKSPACE_ROOT}/${repo}" + if [ -e "$dest/.git" ]; then + echo "Repository already present: $dest" + return + elif [ -e "$dest" ]; then + echo "WARNING: refusing to overwrite non-repository $dest:" + ls -ld "$dest" + return + fi + echo "Cloning Framework-R-D/${repo} into ${dest} ..." + local max_tries=5 current_try=0 + while ! git clone --depth 1 "https://github.com/Framework-R-D/${repo}.git" "$dest"; do + (( ++current_try )) + echo "Attempt $current_try/$max_tries to clone $repo from GitHub FAILED" + (( current_try < max_tries )) || break + sleep 5 + done + if (( current_try == max_tries )); then + echo "WARNING: unable to check out $repo to $dest from GitHub" 1>&2 + fi +} + +clone_if_absent phlex-design +clone_if_absent phlex-examples +clone_if_absent phlex-coding-guidelines +clone_if_absent phlex-spack-recipes diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 62dee182c..db29249ef 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -5,19 +5,56 @@ ### Repository Ecosystem - **Primary Repository**: `Framework-R-D/phlex` -- **Design & Documentation**: `Framework-R-D/phlex-design` (contains design docs, coding guidelines, etc.) +- **Design & Documentation**: `Framework-R-D/phlex-design` (contains design and other documentation) +- **Coding Guidelines**: `Framework-R-D/phlex-coding-guidelines` (coding guidelines for framework contributors) +- **Examples**: `Framework-R-D/phlex-examples` (example user code demonstrating Phlex usage) +- **Spack Recipes**: `Framework-R-D/phlex-spack-recipes` (Spack recipes for Phlex and dependencies) - **Dependencies**: Critical dependency on `FNALssi/cetmodules` for the build system. - **Container Images**: - `phlex-ci`: Used by automated CI checks. - `phlex-dev`: Used for VSCode devcontainers and local development. +### Codespace Layout + +In a GitHub Codespace (or devcontainer), companion repositories are cloned +automatically alongside the primary repository: + +- `/workspaces/phlex` — primary repository (workspace root) +- `/workspaces/phlex-design` — design documentation +- `/workspaces/phlex-examples` — example programs using Phlex +- `/workspaces/phlex-coding-guidelines` — coding guidelines for contributors +- `/workspaces/phlex-spack-recipes` — Spack recipes for Phlex and dependencies + +Use the multi-root workspace file `.devcontainer/codespace.code-workspace` to +open all repositories in a single VS Code window. + ### Development Workflow - **Model**: Fork-based development. Developers should work on branches within their own forks. - **Upstreaming**: Changes are upstreamed via Pull Requests (PRs) to the primary repository `Framework-R-D/phlex`. - **Quality Standards**: - - Adhere to design and coding guidelines in `Framework-R-D/phlex-design`. + - Adhere to design and coding guidelines in + `Framework-R-D/phlex-design` and + `Framework-R-D/phlex-coding-guidelines`, respectively. - Ensure code passes CI checks using the `phlex-ci` environment. + - If you require changes to the `phlex-ci` or `phlex-dev` containers + (or the Spack environments or auxiliary files they use), include + those changes in the PR. + - If an example in `phlex-examples` is rendered obsolete or invalid in + some way, create an issue in the `Framework-R-D/phlex-examples` + project if possible, explaining the conflict and likely changes + required, and notify the user. If it is not possible to create an + issue there, create one in the `phlex` repository if possible. + Failing that, notify the user of the full details of the conflict. + - If your changes require amendment/augmentation of documentation in + `Framework-R-D/phlex-design`, create an issue there if possible, in + `Framework-R-D/phlex` if not, or notify the user of details in the + last resort. + - If your changes require changes or additions to + `Framework-R-D/phlex-spack-recipes`, (e.g. changes to dependency + version requirements or new/removed dependencies), create an issue + there if possible, in `Framework-R-D/phlex` if not, or notify the + user of details in the last resort. - Minimize changes required for upstreaming. ## Communication Guidelines diff --git a/phlex.code-workspace b/phlex.code-workspace index ee7b48a47..c3b663409 100644 --- a/phlex.code-workspace +++ b/phlex.code-workspace @@ -31,7 +31,7 @@ "cmake.useCMakePresets": "always", "cmake.generator": "Ninja", "C_Cpp.default.cStandard": "c17", - "C_Cpp.default.cppStandard": "c++20", + "C_Cpp.default.cppStandard": "c++23", "C_Cpp.default.intelliSenseMode": "linux-gcc-x64", "C_Cpp.default.compileCommands": "${workspaceFolder}/build/compile_commands.json", "C_Cpp.exclusionPolicy": "checkFolders",