Skip to content

Commit 2c56ec7

Browse files
rishichawdarishichawda
committed
add initial copilot instructions
Signed-off-by: Rishi Kumar Chawda <rishichawda@users.noreply.github.com>
1 parent 9760381 commit 2c56ec7

File tree

1 file changed

+372
-0
lines changed

1 file changed

+372
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 372 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,372 @@
1+
# GitHub Copilot Instructions for mixlib-shellout
2+
3+
This document provides comprehensive instructions for AI-assisted development workflow in the mixlib-shellout repository.
4+
5+
## Repository Overview
6+
7+
**mixlib-shellout** is a Ruby gem that provides a simplified interface to shelling out while collecting both standard out and standard error and providing full control over environment, working directory, uid, gid, etc. It's part of the Chef ecosystem and is maintained by Chef Software Inc.
8+
9+
## Repository Structure
10+
11+
```
12+
mixlib-shellout/
13+
├── .expeditor/ # Expeditor CI/CD configuration
14+
│ ├── config.yml # Main Expeditor config
15+
│ ├── run_linux_tests.sh # Linux test runner
16+
│ ├── run_windows_tests.ps1 # Windows test runner
17+
│ ├── update_version.sh # Version update script
18+
│ └── verify.pipeline.yml # Verification pipeline
19+
├── .github/ # GitHub configuration
20+
│ ├── CODEOWNERS # Code ownership rules
21+
│ ├── ISSUE_TEMPLATE/ # Issue templates
22+
│ ├── workflows/ # GitHub Actions workflows
23+
│ └── copilot-instructions.md # This file
24+
├── lib/ # Main library code
25+
│ └── mixlib/
26+
│ ├── shellout.rb # Main ShellOut class
27+
│ └── shellout/
28+
│ ├── exceptions.rb # Custom exceptions
29+
│ ├── helper.rb # Helper utilities
30+
│ ├── unix.rb # Unix-specific implementation
31+
│ ├── version.rb # Gem version
32+
│ ├── windows.rb # Windows-specific implementation
33+
│ └── windows/
34+
│ └── core_ext.rb # Windows core extensions
35+
├── spec/ # RSpec test suite
36+
│ ├── spec_helper.rb # Test configuration
37+
│ ├── mixlib/
38+
│ │ ├── shellout_spec.rb # Main ShellOut tests
39+
│ │ └── shellout/
40+
│ │ ├── helper_spec.rb # Helper tests
41+
│ │ └── windows_spec.rb # Windows-specific tests
42+
│ └── support/ # Test support files
43+
├── Gemfile # Gem dependencies
44+
├── Rakefile # Rake tasks (default: spec)
45+
├── mixlib-shellout.gemspec # Gem specification
46+
├── mixlib-shellout-universal-mingw-ucrt.gemspec # Windows gem spec
47+
├── README.md # Project documentation
48+
├── CHANGELOG.md # Release notes
49+
├── LICENSE # Apache 2.0 License
50+
└── VERSION # Version file
51+
```
52+
53+
## Core Development Workflow
54+
55+
### 1. Task Implementation with Jira Integration
56+
57+
When a Jira ID is provided:
58+
59+
1. **Fetch Jira Issue Details**: Use the MCP server (atlassian-mcp-server) to retrieve issue information:
60+
```
61+
Use the mcp_atlassian-mcp_getJiraIssue tool to fetch issue details
62+
Read the story description, acceptance criteria, and requirements
63+
Understand the scope and context of the task
64+
```
65+
66+
2. **Analyze Requirements**:
67+
- Review the Jira story carefully
68+
- Identify affected components in the codebase
69+
- Determine test scenarios needed
70+
- Plan implementation approach
71+
72+
### 2. Implementation Guidelines
73+
74+
**Code Quality Standards:**
75+
- Follow Ruby best practices and Chef coding standards
76+
- Maintain backward compatibility unless explicitly breaking
77+
- Add comprehensive documentation for new features
78+
- Ensure platform compatibility (Unix/Linux, Windows, macOS)
79+
80+
**File Modification Rules:**
81+
- **DO NOT MODIFY**:
82+
- VERSION file (managed by Expeditor)
83+
- CHANGELOG.md (managed by Expeditor)
84+
- .expeditor/ configuration files
85+
- Gemspec files (unless adding dependencies)
86+
- **SAFE TO MODIFY**:
87+
- lib/ directory (core implementation)
88+
- spec/ directory (tests)
89+
- README.md (documentation updates)
90+
91+
### 3. Testing Requirements
92+
93+
**Mandatory Testing Standards:**
94+
- Maintain code coverage > 80%
95+
- Write unit tests for all new functionality
96+
- Include integration tests for complex features
97+
- Test cross-platform compatibility when applicable
98+
- Use RSpec framework following existing patterns
99+
100+
**Test Structure:**
101+
```ruby
102+
# spec/mixlib/shellout/new_feature_spec.rb
103+
require "spec_helper"
104+
105+
describe Mixlib::ShellOut::NewFeature do
106+
describe "#method_name" do
107+
it "should perform expected behavior" do
108+
# Test implementation
109+
end
110+
111+
context "when edge case occurs" do
112+
it "should handle gracefully" do
113+
# Edge case test
114+
end
115+
end
116+
end
117+
end
118+
```
119+
120+
**Running Tests:**
121+
```bash
122+
# Run all tests
123+
bundle exec rake spec
124+
125+
# Run specific test file
126+
bundle exec rspec spec/mixlib/shellout/feature_spec.rb
127+
128+
# Run with coverage
129+
bundle exec rspec --format documentation
130+
```
131+
132+
### 4. DCO Compliance Requirements
133+
134+
**All commits MUST include a Signed-off-by line:**
135+
```bash
136+
git commit -s -m "Your commit message
137+
138+
Signed-off-by: Your Name <your.email@example.com>"
139+
```
140+
141+
**DCO Requirements:**
142+
- Every commit must be signed off by the author
143+
- Indicates you have read and agree to the Developer Certificate of Origin
144+
- Required for all contributions to Chef projects
145+
- Use `git commit -s` for automatic sign-off
146+
147+
### 5. Pull Request Workflow
148+
149+
**Branch Creation and PR Process:**
150+
151+
1. **Create Feature Branch** (use Jira ID as branch name):
152+
```bash
153+
git checkout -b JIRA-123
154+
```
155+
156+
2. **Implement Changes**:
157+
- Follow the implementation guidelines above
158+
- Write comprehensive tests
159+
- Ensure all tests pass
160+
- Verify code coverage requirements
161+
162+
3. **Commit Changes** (with DCO sign-off):
163+
```bash
164+
git add .
165+
git commit -s -m "Implement feature X for JIRA-123
166+
167+
- Add new functionality to handle Y
168+
- Include comprehensive test coverage
169+
- Update documentation as needed
170+
171+
Signed-off-by: Your Name <your.email@example.com>"
172+
```
173+
174+
4. **Push and Create PR**:
175+
```bash
176+
git push origin JIRA-123
177+
gh pr create --title "JIRA-123: Brief description" --body "$(cat << 'EOF'
178+
<h2>Summary</h2>
179+
<p>Brief description of changes made</p>
180+
181+
<h2>Changes Made</h2>
182+
<ul>
183+
<li>Specific change 1</li>
184+
<li>Specific change 2</li>
185+
</ul>
186+
187+
<h2>Testing</h2>
188+
<ul>
189+
<li>Unit tests added/updated</li>
190+
<li>Integration tests verified</li>
191+
<li>Code coverage maintained > 80%</li>
192+
</ul>
193+
194+
<h2>Jira Reference</h2>
195+
<p>JIRA-123: Link to Jira issue</p>
196+
EOF
197+
)"
198+
```
199+
200+
### 6. Expeditor Build System Integration
201+
202+
**Available Labels for PR Management:**
203+
204+
**Version Management:**
205+
- `Expeditor: Bump Version Major` - Triggers major version bump
206+
- `Expeditor: Bump Version Minor` - Triggers minor version bump
207+
- `Expeditor: Skip Version Bump` - Skips version bump
208+
- `Expeditor: Skip All` - Skips all Expeditor actions
209+
- `Expeditor: Skip Changelog` - Skips changelog update
210+
211+
**Platform Labels:**
212+
- `Platform: AWS` - AWS-specific changes
213+
- `Platform: Azure` - Azure-specific changes
214+
- `Platform: Debian-like` - Debian/Ubuntu-specific
215+
- `Platform: Docker` - Docker-related changes
216+
- `Platform: GCP` - Google Cloud Platform
217+
- `Platform: Linux` - General Linux support
218+
- `Platform: RHEL-like` - RedHat/CentOS/Fedora
219+
- `Platform: SLES-like` - SUSE Linux Enterprise
220+
- `Platform: Unix-like` - General Unix systems
221+
- `Platform: VMware` - VMware-specific
222+
- `Platform: macOS` - macOS-specific
223+
224+
**Aspect Labels:**
225+
- `Aspect: Documentation` - Documentation changes
226+
- `Aspect: Integration` - Integration improvements
227+
- `Aspect: Packaging` - Packaging/distribution
228+
- `Aspect: Performance` - Performance improvements
229+
- `Aspect: Portability` - Cross-platform compatibility
230+
- `Aspect: Security` - Security enhancements
231+
- `Aspect: Stability` - Stability improvements
232+
- `Aspect: Testing` - Test improvements
233+
- `Aspect: UI` - User interface changes
234+
- `Aspect: UX` - User experience improvements
235+
236+
### 7. Prompt-Based Development Process
237+
238+
**All tasks must follow this interactive workflow:**
239+
240+
**Step 1: Task Analysis**
241+
- Analyze Jira issue (if provided)
242+
- Identify scope and requirements
243+
- **PROMPT**: "Task analysis complete. Requirements identified: [summary]. Next step: Plan implementation approach. Continue? [Y/n]"
244+
245+
**Step 2: Implementation Planning**
246+
- Plan code changes and affected files
247+
- Design test strategy
248+
- **PROMPT**: "Implementation plan ready: [summary of approach]. Next step: Begin implementation. Continue? [Y/n]"
249+
250+
**Step 3: Code Implementation**
251+
- Implement core functionality
252+
- **PROMPT**: "Core implementation complete. Files modified: [list]. Next step: Write comprehensive tests. Continue? [Y/n]"
253+
254+
**Step 4: Test Implementation**
255+
- Write unit and integration tests
256+
- Ensure coverage > 80%
257+
- **PROMPT**: "Tests implemented. Coverage: [percentage]. Next step: Run test suite and verify. Continue? [Y/n]"
258+
259+
**Step 5: Testing and Validation**
260+
- Run complete test suite
261+
- Verify all tests pass
262+
- **PROMPT**: "All tests passing. Coverage maintained. Next step: Prepare for PR creation. Continue? [Y/n]"
263+
264+
**Step 6: PR Preparation**
265+
- Create branch with Jira ID
266+
- Commit with DCO sign-off
267+
- **PROMPT**: "Changes committed to branch [branch-name]. Next step: Create pull request. Continue? [Y/n]"
268+
269+
**Step 7: PR Creation**
270+
- Push branch and create PR with comprehensive description
271+
- **PROMPT**: "Pull request created: [PR URL]. Workflow complete. Any additional steps needed?"
272+
273+
### 8. Common Development Patterns
274+
275+
**Adding New ShellOut Options:**
276+
```ruby
277+
# In lib/mixlib/shellout.rb
278+
attr_accessor :new_option
279+
280+
def initialize(command, **options)
281+
# existing code...
282+
@new_option = options[:new_option]
283+
end
284+
```
285+
286+
**Platform-Specific Implementation:**
287+
```ruby
288+
# Add to appropriate platform module
289+
# lib/mixlib/shellout/unix.rb or lib/mixlib/shellout/windows.rb
290+
def platform_specific_method
291+
# Implementation
292+
end
293+
```
294+
295+
**Exception Handling:**
296+
```ruby
297+
# Use existing exception classes from lib/mixlib/shellout/exceptions.rb
298+
raise ShellCommandFailed, "Command failed with status #{exitstatus}"
299+
```
300+
301+
### 9. Documentation Standards
302+
303+
**Code Documentation:**
304+
- Use YARD-style comments for methods
305+
- Include parameter types and return values
306+
- Provide usage examples for public APIs
307+
308+
**README Updates:**
309+
- Update examples when adding new features
310+
- Maintain backward compatibility in examples
311+
- Include platform-specific notes when relevant
312+
313+
**CHANGELOG (managed by Expeditor):**
314+
- Expeditor automatically updates CHANGELOG.md
315+
- Do not manually edit this file
316+
- Ensure PR descriptions are clear for automatic changelog generation
317+
318+
### 10. Quality Assurance Checklist
319+
320+
Before creating a PR, ensure:
321+
322+
- [ ] All tests pass (`bundle exec rake spec`)
323+
- [ ] Code coverage > 80%
324+
- [ ] DCO sign-off on all commits
325+
- [ ] Platform compatibility considered
326+
- [ ] Documentation updated if needed
327+
- [ ] No modification of protected files (VERSION, CHANGELOG.md, .expeditor/)
328+
- [ ] Jira issue requirements fully addressed
329+
- [ ] Appropriate GitHub labels selected
330+
331+
### 11. CI/CD Pipeline
332+
333+
**Expeditor Automation:**
334+
- Automatically bumps version on PR merge (unless skipped)
335+
- Updates CHANGELOG.md based on PR information
336+
- Builds and publishes gems to RubyGems
337+
- Runs comprehensive test suite across platforms
338+
339+
**GitHub Actions:**
340+
- Pull request validation
341+
- Security scanning (TruffleHog)
342+
- Complexity analysis
343+
- SBOM generation
344+
345+
### 12. Emergency Procedures
346+
347+
**Critical Bug Fixes:**
348+
- Use `Expeditor: Bump Version Major` for breaking changes
349+
- Add `Aspect: Security` label for security fixes
350+
- Include detailed testing in PR description
351+
352+
**Release Management:**
353+
- Version bumps are automatic via Expeditor
354+
- Use appropriate Expeditor labels to control versioning
355+
- Major versions require explicit labeling
356+
357+
## Best Practices Summary
358+
359+
1. **Always** fetch and analyze Jira issues when provided
360+
2. **Always** maintain test coverage > 80%
361+
3. **Always** use DCO sign-off on commits
362+
4. **Always** follow prompt-based workflow for transparency
363+
5. **Never** modify VERSION or CHANGELOG.md files
364+
6. **Never** skip testing requirements
365+
7. **Never** create PRs without comprehensive descriptions
366+
8. Use GitHub labels appropriately for CI/CD automation
367+
9. Follow Ruby and Chef coding standards consistently
368+
10. Consider cross-platform compatibility in all changes
369+
370+
---
371+
372+
*This document should be referenced for all development activities in the mixlib-shellout repository. Updates to these instructions should be made through the standard PR process.*

0 commit comments

Comments
 (0)