Skip to content

Enhance Copilot instructions with Spack integration, formatting standards, and Git workflow #320

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
greenc-FNAL merged 5 commits into from
Feb 18, 2026
Merged

Enhance Copilot instructions with Spack integration, formatting standards, and Git workflow #320

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
939bbd8
Add Spack and formatting guidelines to Copilot instructions
Copilot Feb 13, 2026
46b6ed6
Add Git branch management guidance to prevent accidental pushes
Copilot Feb 13, 2026
e65b475
Address review comment
greenc-FNAL Feb 13, 2026
c43e5f8
Clarify setup-env.sh paths in Spack integration section
Copilot Feb 13, 2026
a2feb26
Distinguish agent-specific instructions from general guidance
Copilot Feb 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,29 @@ open all repositories in a single VS Code window.
user of details in the last resort.
- Minimize changes required for upstreaming.

### Git Branch Management

When creating branches for PRs:

- **Do not set upstream tracking at branch creation time**: When creating a new branch for eventual pushing as a new upstream branch (e.g., for a PR), it should not have an upstream tracking branch, even if created based on another branch
- **Rationale**: This eliminates the possibility of accidentally pushing commits to the base branch when pushing the new branch upstream
- **Best practice**: Create branches with `git checkout -b new-branch-name [<base-branch>]` or `git switch --no-track -c new-branch-name [<base-branch>]` without using `--track`, `-t`, or otherwise setting upstream
- **Push new branches**: Use `git push -u origin new-branch-name` only when ready to push the new branch to your fork for the first time; this is when you should set the upstream tracking branch

Example workflow:

```bash
# Create a new feature branch (no tracking)
git checkout -b feature/my-new-feature

# Make changes and commit
git add .
git commit -m "Add new feature"

# Push to your fork (sets tracking only now)
git push -u origin feature/my-new-feature
```

## Communication Guidelines

### Professional Colleague Interaction
Expand Down Expand Up @@ -135,6 +158,26 @@ If the workspace root contains a `srcs/` directory, it may contain symbolic link
- This ensures `find` follows symbolic links and discovers all actual source files
- Without this flag, `find` will skip linked directories and miss significant portions of the codebase

### Spack Package Manager Integration

The project uses Spack for dependency management in development and CI environments:

- **Spack Environments**: The `scripts/setup-env.sh` script automatically activates Spack environments when available
- **Loading Additional Packages**: If you need tools or libraries not loaded by default, use `spack load <package>` to bring them into the environment
- **Common Use Cases**:
- `spack load cmake` - Load CMake if not in current environment
- `spack load gcc` - Load specific GCC compiler
- `spack load ninja` - Load Ninja build tool
- `spack load gcovr` - Load coverage reporting tools
- **Graceful Degradation**: The build system works with system-installed packages when Spack is unavailable
- **Recipe Repository**: Changes to Spack recipes should be proposed to `Framework-R-D/phlex-spack-recipes`

When suggesting installation of dependencies:

- Prefer sourcing the environment setup script (`scripts/setup-env.sh` or workspace-level `setup-env.sh`) as it handles both Spack and system packages
- For manual installations, provide both Spack (`spack install/load`) and system package manager options
- Consult `scripts/README.md` and `scripts/QUICK_REFERENCE.md` for common patterns

## Text Formatting Standards

### CRITICAL: Apply to ALL files you create or edit (bash scripts, Python, C++, YAML, Markdown, etc.)
Expand Down Expand Up @@ -189,11 +232,32 @@ If a feature (e.g., lock guards) is conspicuously missing, add a comment explain

## Code Formatting Standards

### C++ Files

- Use clang-format tool for all C++ code (VS Code auto-formats on save)
- Configuration defined in `.clang-format` (100-character line limit, 2-space indentation)
- Follow clang-tidy recommendations defined in `.clang-tidy`
- CI automatically checks formatting and provides fix suggestions

### Python Files

- Use ruff for formatting and linting (configured in `pyproject.toml`)
- Follow Google-style docstring conventions
- Line length: 99 characters
- Use double quotes for strings
- Type hints recommended (mypy configured in `pyproject.toml`)

### CMake Files

- Use cmake-format tool (VS Code auto-formats on save)
- Configuration: `dangle_align: "child"`, `dangle_parens: true`

### Jsonnet Files

- Jsonnet configuration files (`.jsonnet`) are used for Phlex workflow configurations
- Follow consistent formatting as enforced by CI checks
Copy link
Member

@knoepfel knoepfel Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This instruction seems a little indirect--perhaps it's better to say Follow consistent formatting as enforced by jsonnetfmt?

Copy link
Contributor

@greenc-FNAL greenc-FNAL Feb 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We certainly could; this is AI's own wording, supposedly to be the most clear to itself. Presumably at this point it will read the workflows and work out what needs to be done?

Copy link
Member

@knoepfel knoepfel Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess I was thinking in the context of someone's interactive development environment via (e.g.) Visual Studio Code. If they're using an agent in their Copilot chat, won't this file be used for instructions? If so, it seems less likely that someone's interactive session would have ready access to the workflow logs than if they had access to jsonnetfmt. But maybe I'm misunderstanding the purpose of these instructions.

Copy link
Contributor

@greenc-FNAL greenc-FNAL Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instructions were generated by AI specifically to improve agent behavior. I will try to distinguish agent-specific instructions from those relevant for interactive use.

- Primarily used in test configurations (e.g., `test/python/*.jsonnet`)

## Markdown Rules

All Markdown files must strictly follow these markdownlint rules:
Expand Down
Loading