Skip to content

Commit 5987e5c

Browse files
markphipmarkphip
authored
Merge pull request #79 from microsoft/copilot/fix-78
✨ Set up Copilot instructions for devcontainer features repository
2 parents c84656c + be35388 commit 5987e5c

File tree

1 file changed

+201
-0
lines changed

1 file changed

+201
-0
lines changed

‎.copilot-instructions.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
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 (auto-generated, do not edit manually)
17+
- Optional: `NOTES.md` - Implementation notes that get included in README.md generation (auto-generated, do not edit manually)
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+
### Semantic Versioning
38+
Features use [semantic versioning (SemVer)](https://semver.org/):
39+
- **MAJOR** version for incompatible API changes
40+
- **MINOR** version for backward-compatible functionality additions
41+
- **PATCH** version for backward-compatible bug fixes
42+
43+
When making changes to a feature:
44+
1. Update the `version` field in `devcontainer-feature.json`
45+
2. Follow SemVer guidelines based on the type of change
46+
3. Document breaking changes in the feature description or NOTES.md
47+
48+
### Creating a New Feature
49+
1. Create directory structure: `/src/{feature-name}/`
50+
2. Write `devcontainer-feature.json` with proper metadata:
51+
```json
52+
{
53+
"id": "feature-name",
54+
"version": "1.0.0",
55+
"name": "Feature Display Name",
56+
"description": "Brief description",
57+
"options": { /* configuration options */ },
58+
"installsAfter": ["ghcr.io/devcontainers/features/common-utils"]
59+
}
60+
```
61+
3. Implement `install.sh` with proper error handling and logging
62+
4. Create comprehensive tests in `/test/{feature-name}/`
63+
64+
### Feature Implementation Best Practices
65+
- **Error Handling**: Always check exit codes and handle failures gracefully
66+
- **Logging**: Use consistent logging format with feature name and version
67+
- **Idempotency**: Features should handle multiple installations safely
68+
- **Cross-Platform**: Test on Ubuntu, Debian, and Mariner Linux base images
69+
- **Dependencies**: Use `installsAfter` for proper installation order
70+
71+
### Testing Requirements
72+
- Create `scenarios.json` with comprehensive test cases
73+
- Test on multiple base images: Ubuntu, Debian, Mariner
74+
- Include edge cases: version conflicts, reinstallation, error conditions
75+
- Use descriptive test names that explain what is being validated
76+
77+
### Test Execution
78+
```bash
79+
# Test single feature on specific base image
80+
devcontainer features test -f {feature-name} -i {base-image} .
81+
82+
# Test feature autogenerated scenarios only (CI pattern)
83+
devcontainer features test --skip-scenarios -f {feature-name} -i {base-image} .
84+
85+
# Test feature custom scenarios only (CI pattern)
86+
devcontainer features test -f {feature-name} --skip-autogenerated .
87+
88+
# Test all global scenarios
89+
devcontainer features test --global-scenarios-only .
90+
91+
# Common base images used in CI
92+
# - mcr.microsoft.com/devcontainers/base:ubuntu
93+
# - mcr.microsoft.com/devcontainers/base:debian
94+
# - mcr.microsoft.com/cbl-mariner/base/core:2.0
95+
```
96+
97+
## CI/CD Workflows
98+
99+
### Automated Testing
100+
- `test-pr.yaml` - Tests changed features on pull requests using path filtering
101+
- `test-all.yaml` - Comprehensive testing on main branch across all features
102+
- Tests run on Ubuntu, Debian, and Mariner base images automatically
103+
- Separate jobs for autogenerated tests and custom scenarios
104+
105+
### Release Process
106+
- `release.yaml` - Publishes features to GitHub Container Registry
107+
- Features are versioned using semantic versioning
108+
- Each feature is published independently
109+
110+
## Code Quality Standards
111+
112+
### Shell Script Guidelines
113+
- Use `set -e` for error handling
114+
- Quote variables properly: `"${VARIABLE}"`
115+
- Check for required tools before using them
116+
- Provide meaningful error messages
117+
- Follow consistent indentation and formatting
118+
119+
### JSON Configuration
120+
- Use proper JSON validation
121+
- Follow devcontainer feature schema
122+
- Include comprehensive option descriptions
123+
- Specify version constraints clearly
124+
125+
## Common Patterns
126+
127+
### Package Installation
128+
```bash
129+
# Check for package manager
130+
if command -v apt-get >/dev/null 2>&1; then
131+
package_manager="apt"
132+
elif command -v tdnf >/dev/null 2>&1; then
133+
package_manager="tdnf"
134+
fi
135+
```
136+
137+
### Version Detection
138+
```bash
139+
# Auto-detect latest version
140+
if [ "${VERSION}" = "latest" ] || [ "${VERSION}" = "lts" ]; then
141+
VERSION=$(curl -s API_ENDPOINT | jq -r .tag_name | sed 's/^v//')
142+
fi
143+
```
144+
145+
### Cross-Platform Compatibility
146+
- Test on Ubuntu (apt), Debian (apt), and Mariner (tdnf)
147+
- Handle different package names across distributions
148+
- Account for different default paths and permissions
149+
150+
## Debugging and Troubleshooting
151+
152+
### Common Issues
153+
1. **Network timeouts**: Features may fail in environments with restricted internet
154+
2. **Package conflicts**: Check for existing installations before proceeding
155+
3. **Permission issues**: Ensure proper file permissions and user context
156+
4. **Path problems**: Verify PATH updates and binary locations
157+
158+
### Debugging Tools
159+
- Check feature logs in devcontainer build output
160+
- Test locally using devcontainer CLI
161+
- Use `docker exec` to inspect container state
162+
- Review GitHub Actions logs for CI failures
163+
164+
## Security Considerations
165+
166+
### Best Practices
167+
- Validate all input parameters
168+
- Use secure download methods (HTTPS, signature verification)
169+
- Avoid hardcoded credentials or secrets
170+
- Follow principle of least privilege
171+
- Pin dependency versions for reproducibility
172+
173+
### Secrets and Credentials
174+
- Use devcontainer secrets for sensitive data
175+
- Never commit credentials to the repository
176+
- Support both build-time and runtime authentication methods
177+
178+
## Contributing Guidelines
179+
180+
### Pull Request Process
181+
1. Create feature branch from `main`
182+
2. Implement feature with comprehensive tests
183+
3. Update the `version` field in `devcontainer-feature.json` following semantic versioning
184+
4. Ensure all CI checks pass
185+
5. Update documentation as needed
186+
6. Request review from maintainers
187+
188+
### Code Review Checklist
189+
- [ ] Feature follows repository conventions
190+
- [ ] Tests cover success and failure scenarios
191+
- [ ] Cross-platform compatibility verified
192+
- [ ] Security best practices followed
193+
- [ ] Documentation is complete and accurate
194+
195+
## Support and Resources
196+
197+
- [DevContainer Features Specification](https://containers.dev/implementors/features/)
198+
- [DevContainer CLI Documentation](https://github.com/devcontainers/cli)
199+
- [GitHub Codespaces Documentation](https://docs.github.com/en/codespaces)
200+
201+
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)