mirror of
https://github.com/dwinkler1/np.git
synced 2026-02-19 22:40:57 -05:00
Merge pull request #60 from dwinkler1/copilot/setup-copilot-instructions
Add GitHub Copilot instructions for repository context
This commit is contained in:
GitHub
commit
c29efd219c
1 changed files with 194 additions and 0 deletions
194
.github/copilot-instructions.md
vendored
Normal file
194
.github/copilot-instructions.md
vendored
Normal file
|
|
@ -0,0 +1,194 @@
|
|||
# GitHub Copilot Instructions for np Repository
|
||||
|
||||
## Repository Overview
|
||||
|
||||
This repository provides Nix flake templates for setting up Research Development Environments (RDE). The primary template is located in `templates/rde/` and is designed for data science and research projects supporting R, Python, and Julia.
|
||||
|
||||
## Project Structure
|
||||
|
||||
- `flake.nix` - Root flake defining available templates
|
||||
- `templates/rde/` - Main RDE template with Neovim-based development environment
|
||||
- `flake.nix` - Template flake configuration with language support and tooling
|
||||
- `flake.lock` - Locked dependencies for reproducibility
|
||||
- `.envrc` - direnv configuration for automatic environment loading
|
||||
- `.github/workflows/` - CI/CD workflows for testing and updates
|
||||
- `check.yml` - Tests RDE template on Ubuntu
|
||||
- `check_macos.yml` - Tests RDE template on macOS
|
||||
- `update.yml` - Automated daily dependency updates
|
||||
|
||||
## Key Technologies
|
||||
|
||||
- **Nix Flakes**: Reproducible development environments
|
||||
- **nixCats**: Custom Neovim configuration framework
|
||||
- **direnv**: Automatic environment loading
|
||||
- **Cachix**: Binary cache for faster builds (using `rde`, `rstats-on-nix`, and `nix-community` caches)
|
||||
|
||||
## Language Support
|
||||
|
||||
The RDE template supports multiple languages, controlled via `config.enabledLanguages` in `templates/rde/flake.nix`:
|
||||
|
||||
- **R**: R wrapper, Quarto, air-formatter, language server, and custom R packages via overlays
|
||||
- **Python**: Python 3, basedpyright LSP, UV package manager
|
||||
- **Julia**: Julia REPL with Pluto.jl support
|
||||
|
||||
## Development Commands
|
||||
|
||||
The template provides project-specific commands (prefix with package name, default is `p`):
|
||||
|
||||
- `p` - Launch Neovim
|
||||
- `p-g` - Launch Neovide GUI
|
||||
- `p-initProject` - Initialize project structure (data/, src/, docs/)
|
||||
- `p-updateDeps` - Update all dependencies (flake inputs, R packages, Python packages)
|
||||
- `p-r` - Launch R console
|
||||
- `p-py` / `p-ipy` - Launch Python/IPython REPL
|
||||
- `p-marimo` - Launch Marimo notebook
|
||||
- `p-jl` - Launch Julia REPL
|
||||
- `p-pluto` - Launch Pluto.jl notebook
|
||||
- `p-devenv` - Devenv integration (when enabled)
|
||||
|
||||
## Nix Flake Conventions
|
||||
|
||||
### Configuration Structure
|
||||
|
||||
The RDE template uses a centralized `config` object at the top of `flake.nix`:
|
||||
|
||||
```nix
|
||||
config = rec {
|
||||
defaultPackageName = "p";
|
||||
enabledLanguages = { julia = false; python = false; r = true; };
|
||||
enabledPackages = { gitPlugins = enabledLanguages.r; devenv = false; };
|
||||
theme = { colorscheme = "kanagawa"; background = "dark"; };
|
||||
};
|
||||
```
|
||||
|
||||
### Overlays Pattern
|
||||
|
||||
The template uses multiple overlays to extend nixpkgs:
|
||||
|
||||
- `rOverlay` - Adds R packages via rix/rstats-on-nix
|
||||
- `pythonOverlay` - Configures Python packages
|
||||
- `rixOverlay` - Integrates R package snapshots from rstats-on-nix
|
||||
- `projectScriptsOverlay` - Custom shell scripts for project management
|
||||
- `extraPkgOverlay` - Additional theme and plugin configuration
|
||||
|
||||
### Package Categories
|
||||
|
||||
nixCats uses categories to organize functionality:
|
||||
|
||||
- `lspsAndRuntimeDeps` - Language servers and runtime dependencies
|
||||
- `startupPlugins` - Neovim plugins loaded at startup
|
||||
- `optionalPlugins` - Plugins loaded on demand
|
||||
- `environmentVariables` - Language-specific environment setup
|
||||
- `extraWrapperArgs` - Additional wrapper arguments (e.g., unset PYTHONPATH for Python)
|
||||
|
||||
## Testing & CI/CD
|
||||
|
||||
### Local Testing
|
||||
|
||||
```bash
|
||||
# Build the RDE template
|
||||
nix build ./templates/rde
|
||||
|
||||
# Check the RDE template
|
||||
nix flake check ./templates/rde
|
||||
|
||||
# Enter development shell
|
||||
nix develop ./templates/rde
|
||||
```
|
||||
|
||||
### CI Workflows
|
||||
|
||||
- **check.yml**: Runs on pushes to `templates/rde/flake.lock`, builds and checks the template on Ubuntu
|
||||
- **check_macos.yml**: Tests on macOS when `update_rde` branch is pushed
|
||||
- **update.yml**: Daily cron job that updates dependencies via `p-updateDeps` and creates PRs
|
||||
|
||||
## Dependency Management
|
||||
|
||||
### R Packages
|
||||
|
||||
R packages are managed through rstats-on-nix pinned snapshots. The date is specified in the `rixpkgs.url` input:
|
||||
|
||||
```nix
|
||||
rixpkgs.url = "github:rstats-on-nix/nixpkgs/2025-12-15";
|
||||
```
|
||||
|
||||
Custom R packages can be added in `rOverlay` or via `r-packages.nix` file.
|
||||
|
||||
### Python Packages
|
||||
|
||||
Python packages use UV for management with nixpkgs Python as the interpreter:
|
||||
|
||||
- Environment variables force UV to use nix Python: `UV_PYTHON_DOWNLOADS = "never"` and `UV_PYTHON = pkgs.python.interpreter`
|
||||
- PYTHONPATH is explicitly unset via `extraWrapperArgs`
|
||||
|
||||
### Flake Inputs
|
||||
|
||||
Dependencies are tracked in `flake.lock`. Key inputs include:
|
||||
|
||||
- `nixpkgs` - NixOS 25.11
|
||||
- `rixpkgs` - R package snapshots from rstats-on-nix
|
||||
- `nixCats` - Custom Neovim configuration framework
|
||||
- `fran` - Extra R packages overlay
|
||||
- Plugin inputs for R.nvim ecosystem
|
||||
|
||||
## Coding Style & Conventions
|
||||
|
||||
1. **Nix Code**:
|
||||
- Use `rec` for recursive attribute sets when needed
|
||||
- Prefer `let...in` for local bindings
|
||||
- Use `lib.optional` and `lib.optionalString` for conditional inclusion
|
||||
- Keep configuration at the top of the file for easy customization
|
||||
|
||||
2. **Shell Scripts** (in overlays):
|
||||
- Always use `set -euo pipefail` for safety
|
||||
- Provide user-friendly output with emojis and clear messages
|
||||
- Check for existing files/directories before creating
|
||||
|
||||
3. **Workflows**:
|
||||
- Use `workflow_dispatch` for manual triggering
|
||||
- Configure concurrency to cancel in-progress runs
|
||||
- Use Cachix for binary caching with multiple caches
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Adding a New Language
|
||||
|
||||
1. Add to `config.enabledLanguages`
|
||||
2. Create overlay for language-specific packages
|
||||
3. Add to `categoryDefinitions.lspsAndRuntimeDeps`
|
||||
4. Add command aliases in `packageDefinitions.hosts`
|
||||
5. Update `shellHook` with available commands
|
||||
|
||||
### Adding Custom Scripts
|
||||
|
||||
Add to `projectScriptsOverlay`:
|
||||
|
||||
```nix
|
||||
myScript = prev.writeShellScriptBin "myScript" ''
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
# script content
|
||||
'';
|
||||
```
|
||||
|
||||
### Plugin Integration
|
||||
|
||||
For git-based plugins:
|
||||
1. Add flake input with `flake = false`
|
||||
2. Reference in nixCats inputs
|
||||
3. Add to `startupPlugins` or `optionalPlugins` categories
|
||||
|
||||
## Important Notes
|
||||
|
||||
- The template creates a `.gitignore` that excludes data files by default
|
||||
- R packages are installed to project-local `.Rlibs/` directory
|
||||
- Python UV is configured to never download Python, always using nixpkgs version
|
||||
- The template supports multiple platforms: x86_64-linux, aarch64-linux, aarch64-darwin
|
||||
- Neovim is wrapped with language-specific environment variables and PATH additions
|
||||
|
||||
## File Generation
|
||||
|
||||
When asked to initialize projects or generate common files, follow the patterns in:
|
||||
- `initProjectScript` for project structure
|
||||
- `.gitignore` template for what to exclude
|
||||
- `README.md` template for documentation structure
|
||||
Loading…
Add table
Add a link
Reference in a new issue