Skip to content

Commit e309196

Browse files
Copilotmarkphip
Copilot
and
markphip
committed
Add comprehensive Copilot instructions for devcontainer features repository
Co-authored-by: markphip <933108+markphip@users.noreply.github.com>
1 parent 1eeee04 commit e309196

File tree

1 file changed

+189
-0
lines changed

1 file changed

+189
-0
lines changed

‎.copilot-instructions.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Copilot Instructions for Codespace Features Repository
2+
3+
This repository contains [devcontainer features](https://containers.dev/implementors/features/) to assist teams in adopting GitHub Codespaces. Features are reusable "plugins" that can be installed into devcontainers to add tools, languages, or services.
4+
5+
## Repository Structure
6+
7+
### Core Components
8+
- `/src/` - Contains all feature implementations, each in its own subdirectory
9+
- `/test/` - Contains test scenarios for each feature, plus global integration tests
10+
- `/.github/workflows/` - CI/CD automation for testing and releasing features
11+
12+
### Feature Structure
13+
Each feature in `/src/{feature-name}/` contains:
14+
- `devcontainer-feature.json` - Feature metadata, options, and configuration
15+
- `install.sh` - Installation script (main implementation)
16+
- `README.md` - Feature documentation
17+
- Optional: `NOTES.md` for implementation notes
18+
19+
### Testing Structure
20+
- `/test/{feature-name}/` - Feature-specific tests with `scenarios.json` and test scripts
21+
- `/test/_global/` - Integration tests that test multiple features together
22+
- Test scenarios are defined in `scenarios.json` files and executed using the devcontainer CLI
23+
24+
## Current Features
25+
26+
| Feature | Description |
27+
|---------|-------------|
28+
| `artifacts-helper` | Azure Artifacts credential helper for Codespace authentication |
29+
| `devtool` | Microsoft DevTool (internal only) |
30+
| `docfx` | DocFX documentation generation tool |
31+
| `external-repository` | Handles external git repository integration in Codespaces |
32+
| `go` | Go language with Mariner Linux support |
33+
| `microsoft-git` | Microsoft's Git distribution with Scalar and GVFS |
34+
35+
## Development Guidelines
36+
37+
### Creating a New Feature
38+
1. Create directory structure: `/src/{feature-name}/`
39+
2. Write `devcontainer-feature.json` with proper metadata:
40+
```json
41+
{
42+
"id": "feature-name",
43+
"version": "1.0.0",
44+
"name": "Feature Display Name",
45+
"description": "Brief description",
46+
"options": { /* configuration options */ },
47+
"installsAfter": ["ghcr.io/devcontainers/features/common-utils"]
48+
}
49+
```
50+
3. Implement `install.sh` with proper error handling and logging
51+
4. Create comprehensive tests in `/test/{feature-name}/`
52+
53+
### Feature Implementation Best Practices
54+
- **Error Handling**: Always check exit codes and handle failures gracefully
55+
- **Logging**: Use consistent logging format with feature name and version
56+
- **Idempotency**: Features should handle multiple installations safely
57+
- **Cross-Platform**: Test on Ubuntu, Debian, and Mariner Linux base images
58+
- **Dependencies**: Use `installsAfter` for proper installation order
59+
60+
### Testing Requirements
61+
- Create `scenarios.json` with comprehensive test cases
62+
- Test on multiple base images: Ubuntu, Debian, Mariner
63+
- Include edge cases: version conflicts, reinstallation, error conditions
64+
- Use descriptive test names that explain what is being validated
65+
66+
### Test Execution
67+
```bash
68+
# Test single feature on specific base image
69+
devcontainer features test -f {feature-name} -i {base-image} .
70+
71+
# Test feature autogenerated scenarios only (CI pattern)
72+
devcontainer features test --skip-scenarios -f {feature-name} -i {base-image} .
73+
74+
# Test feature custom scenarios only (CI pattern)
75+
devcontainer features test -f {feature-name} --skip-autogenerated .
76+
77+
# Test all global scenarios
78+
devcontainer features test --global-scenarios-only .
79+
80+
# Common base images used in CI
81+
# - mcr.microsoft.com/devcontainers/base:ubuntu
82+
# - mcr.microsoft.com/devcontainers/base:debian
83+
# - mcr.microsoft.com/cbl-mariner/base/core:2.0
84+
```
85+
86+
## CI/CD Workflows
87+
88+
### Automated Testing
89+
- `test-pr.yaml` - Tests changed features on pull requests using path filtering
90+
- `test-all.yaml` - Comprehensive testing on main branch across all features
91+
- Tests run on Ubuntu, Debian, and Mariner base images automatically
92+
- Separate jobs for autogenerated tests and custom scenarios
93+
94+
### Release Process
95+
- `release.yaml` - Publishes features to GitHub Container Registry
96+
- Features are versioned using semantic versioning
97+
- Each feature is published independently
98+
99+
## Code Quality Standards
100+
101+
### Shell Script Guidelines
102+
- Use `set -e` for error handling
103+
- Quote variables properly: `"${VARIABLE}"`
104+
- Check for required tools before using them
105+
- Provide meaningful error messages
106+
- Follow consistent indentation and formatting
107+
108+
### JSON Configuration
109+
- Use proper JSON validation
110+
- Follow devcontainer feature schema
111+
- Include comprehensive option descriptions
112+
- Specify version constraints clearly
113+
114+
## Common Patterns
115+
116+
### Package Installation
117+
```bash
118+
# Check for package manager
119+
if command -v apt-get >/dev/null 2>&1; then
120+
package_manager="apt"
121+
elif command -v tdnf >/dev/null 2>&1; then
122+
package_manager="tdnf"
123+
fi
124+
```
125+
126+
### Version Detection
127+
```bash
128+
# Auto-detect latest version
129+
if [ "${VERSION}" = "latest" ] || [ "${VERSION}" = "lts" ]; then
130+
VERSION=$(curl -s API_ENDPOINT | jq -r .tag_name | sed 's/^v//')
131+
fi
132+
```
133+
134+
### Cross-Platform Compatibility
135+
- Test on Ubuntu (apt), Debian (apt), and Mariner (tdnf)
136+
- Handle different package names across distributions
137+
- Account for different default paths and permissions
138+
139+
## Debugging and Troubleshooting
140+
141+
### Common Issues
142+
1. **Network timeouts**: Features may fail in environments with restricted internet
143+
2. **Package conflicts**: Check for existing installations before proceeding
144+
3. **Permission issues**: Ensure proper file permissions and user context
145+
4. **Path problems**: Verify PATH updates and binary locations
146+
147+
### Debugging Tools
148+
- Check feature logs in devcontainer build output
149+
- Test locally using devcontainer CLI
150+
- Use `docker exec` to inspect container state
151+
- Review GitHub Actions logs for CI failures
152+
153+
## Security Considerations
154+
155+
### Best Practices
156+
- Validate all input parameters
157+
- Use secure download methods (HTTPS, signature verification)
158+
- Avoid hardcoded credentials or secrets
159+
- Follow principle of least privilege
160+
- Pin dependency versions for reproducibility
161+
162+
### Secrets and Credentials
163+
- Use devcontainer secrets for sensitive data
164+
- Never commit credentials to the repository
165+
- Support both build-time and runtime authentication methods
166+
167+
## Contributing Guidelines
168+
169+
### Pull Request Process
170+
1. Create feature branch from `main`
171+
2. Implement feature with comprehensive tests
172+
3. Ensure all CI checks pass
173+
4. Update documentation as needed
174+
5. Request review from maintainers
175+
176+
### Code Review Checklist
177+
- [ ] Feature follows repository conventions
178+
- [ ] Tests cover success and failure scenarios
179+
- [ ] Cross-platform compatibility verified
180+
- [ ] Security best practices followed
181+
- [ ] Documentation is complete and accurate
182+
183+
## Support and Resources
184+
185+
- [DevContainer Features Specification](https://containers.dev/implementors/features/)
186+
- [DevContainer CLI Documentation](https://github.com/devcontainers/cli)
187+
- [GitHub Codespaces Documentation](https://docs.github.com/en/codespaces)
188+
189+
When working on this repository, focus on creating reliable, cross-platform features that enhance the Codespaces development experience while following established patterns and best practices.

0 commit comments

Comments
 (0)