✨ Set up Copilot instructions for devcontainer features repository with versioning guidelines

.copilot-instructions.md

@@ -0,0 +1,201 @@
+# Copilot Instructions for Codespace Features Repository
+
+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.
+
+## Repository Structure
+
+### Core Components
+- `/src/` - Contains all feature implementations, each in its own subdirectory
+- `/test/` - Contains test scenarios for each feature, plus global integration tests
+- `/.github/workflows/` - CI/CD automation for testing and releasing features
+
+### Feature Structure
+Each feature in `/src/{feature-name}/` contains:
+- `devcontainer-feature.json` - Feature metadata, options, and configuration
+- `install.sh` - Installation script (main implementation)
+- `README.md` - Feature documentation (auto-generated, do not edit manually)
+- Optional: `NOTES.md` - Implementation notes that get included in README.md generation (auto-generated, do not edit manually)
+
+### Testing Structure
+- `/test/{feature-name}/` - Feature-specific tests with `scenarios.json` and test scripts
+- `/test/_global/` - Integration tests that test multiple features together
+- Test scenarios are defined in `scenarios.json` files and executed using the devcontainer CLI
+
+## Current Features
+
+| Feature | Description |
+|---------|-------------|
+| `artifacts-helper` | Azure Artifacts credential helper for Codespace authentication |
+| `devtool` | Microsoft DevTool (internal only) |
+| `docfx` | DocFX documentation generation tool |
+| `external-repository` | Handles external git repository integration in Codespaces |
+| `go` | Go language with Mariner Linux support |
+| `microsoft-git` | Microsoft's Git distribution with Scalar and GVFS |
+
+## Development Guidelines
+
+### Semantic Versioning
+Features use [semantic versioning (SemVer)](https://semver.org/):
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for backward-compatible functionality additions
+- **PATCH** version for backward-compatible bug fixes
+
+When making changes to a feature:
+1. Update the `version` field in `devcontainer-feature.json`
+2. Follow SemVer guidelines based on the type of change
+3. Document breaking changes in the feature description or NOTES.md
+
+### Creating a New Feature
+1. Create directory structure: `/src/{feature-name}/`
+2. Write `devcontainer-feature.json` with proper metadata:
+   ```json
+   {
+     "id": "feature-name",
+     "version": "1.0.0",
+     "name": "Feature Display Name",
+     "description": "Brief description",
+     "options": { /* configuration options */ },
+     "installsAfter": ["ghcr.io/devcontainers/features/common-utils"]
+   }
+   ```
+3. Implement `install.sh` with proper error handling and logging
+4. Create comprehensive tests in `/test/{feature-name}/`
+
+### Feature Implementation Best Practices
+- **Error Handling**: Always check exit codes and handle failures gracefully
+- **Logging**: Use consistent logging format with feature name and version
+- **Idempotency**: Features should handle multiple installations safely
+- **Cross-Platform**: Test on Ubuntu, Debian, and Mariner Linux base images
+- **Dependencies**: Use `installsAfter` for proper installation order
+
+### Testing Requirements
+- Create `scenarios.json` with comprehensive test cases
+- Test on multiple base images: Ubuntu, Debian, Mariner
+- Include edge cases: version conflicts, reinstallation, error conditions
+- Use descriptive test names that explain what is being validated
+
+### Test Execution
+```bash
+# Test single feature on specific base image
+devcontainer features test -f {feature-name} -i {base-image} .
+
+# Test feature autogenerated scenarios only (CI pattern)
+devcontainer features test --skip-scenarios -f {feature-name} -i {base-image} .
+
+# Test feature custom scenarios only (CI pattern)
+devcontainer features test -f {feature-name} --skip-autogenerated .
+
+# Test all global scenarios
+devcontainer features test --global-scenarios-only .
+
+# Common base images used in CI
+# - mcr.microsoft.com/devcontainers/base:ubuntu
+# - mcr.microsoft.com/devcontainers/base:debian  
+# - mcr.microsoft.com/cbl-mariner/base/core:2.0
+```
+
+## CI/CD Workflows
+
+### Automated Testing
+- `test-pr.yaml` - Tests changed features on pull requests using path filtering
+- `test-all.yaml` - Comprehensive testing on main branch across all features
+- Tests run on Ubuntu, Debian, and Mariner base images automatically
+- Separate jobs for autogenerated tests and custom scenarios
+
+### Release Process
+- `release.yaml` - Publishes features to GitHub Container Registry
+- Features are versioned using semantic versioning
+- Each feature is published independently
+
+## Code Quality Standards
+
+### Shell Script Guidelines
+- Use `set -e` for error handling
+- Quote variables properly: `"${VARIABLE}"`
+- Check for required tools before using them
+- Provide meaningful error messages
+- Follow consistent indentation and formatting
+
+### JSON Configuration
+- Use proper JSON validation
+- Follow devcontainer feature schema
+- Include comprehensive option descriptions
+- Specify version constraints clearly
+
+## Common Patterns
+
+### Package Installation
+```bash
+# Check for package manager
+if command -v apt-get >/dev/null 2>&1; then
+    package_manager="apt"
+elif command -v tdnf >/dev/null 2>&1; then
+    package_manager="tdnf"
+fi
+```
+
+### Version Detection
+```bash
+# Auto-detect latest version
+if [ "${VERSION}" = "latest" ] || [ "${VERSION}" = "lts" ]; then
+    VERSION=$(curl -s API_ENDPOINT | jq -r .tag_name | sed 's/^v//')
+fi
+```
+
+### Cross-Platform Compatibility
+- Test on Ubuntu (apt), Debian (apt), and Mariner (tdnf)
+- Handle different package names across distributions
+- Account for different default paths and permissions
+
+## Debugging and Troubleshooting
+
+### Common Issues
+1. **Network timeouts**: Features may fail in environments with restricted internet
+2. **Package conflicts**: Check for existing installations before proceeding
+3. **Permission issues**: Ensure proper file permissions and user context
+4. **Path problems**: Verify PATH updates and binary locations
+
+### Debugging Tools
+- Check feature logs in devcontainer build output
+- Test locally using devcontainer CLI
+- Use `docker exec` to inspect container state
+- Review GitHub Actions logs for CI failures
+
+## Security Considerations
+
+### Best Practices
+- Validate all input parameters
+- Use secure download methods (HTTPS, signature verification)
+- Avoid hardcoded credentials or secrets
+- Follow principle of least privilege
+- Pin dependency versions for reproducibility
+
+### Secrets and Credentials
+- Use devcontainer secrets for sensitive data
+- Never commit credentials to the repository
+- Support both build-time and runtime authentication methods
+
+## Contributing Guidelines
+
+### Pull Request Process
+1. Create feature branch from `main`
+2. Implement feature with comprehensive tests
+3. Update the `version` field in `devcontainer-feature.json` following semantic versioning
+4. Ensure all CI checks pass
+5. Update documentation as needed
+6. Request review from maintainers
+
+### Code Review Checklist
+- [ ] Feature follows repository conventions
+- [ ] Tests cover success and failure scenarios
+- [ ] Cross-platform compatibility verified
+- [ ] Security best practices followed
+- [ ] Documentation is complete and accurate
+
+## Support and Resources
+
+- [DevContainer Features Specification](https://containers.dev/implementors/features/)
+- [DevContainer CLI Documentation](https://github.com/devcontainers/cli)
+- [GitHub Codespaces Documentation](https://docs.github.com/en/codespaces)
+
+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.