Skip to content

Commit 2273ff4

Browse files
tpowell-progresstpowell-progress
authored
Merge pull request #10 from chef/rishichawda/set-up-ai-assisted-development-workflow
set up ai assisted development workflow
2 parents ec320c9 + 870656a commit 2273ff4

File tree

2 files changed

+323
-0
lines changed

2 files changed

+323
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
# GitHub Copilot Instructions for chef-gyoku
2+
3+
## Repository Overview
4+
5+
The `chef-gyoku` repository is a Ruby gem that translates Ruby Hashes to XML. This is a Chef-maintained fork of the original Gyoku gem with Chef-specific customizations and requirements.
6+
7+
### Project Structure
8+
9+
```
10+
chef-gyoku/
11+
├── .github/
12+
│ ├── workflows/
13+
│ │ ├── ci.yml # CI pipeline for Ruby 3.1 & 3.4
14+
│ │ └── lint.yml # Cookstyle linting workflow
15+
│ ├── dependabot.yml # Dependency management
16+
│ └── copilot-instructions.md # This file
17+
├── lib/
18+
│ ├── chef-gyoku.rb # Main entry point
19+
│ └── chef-gyoku/
20+
│ ├── array.rb # Array to XML conversion
21+
│ ├── hash.rb # Hash to XML conversion
22+
│ ├── prettifier.rb # XML prettification
23+
│ ├── version.rb # Gem version
24+
│ ├── xml_key.rb # XML key handling
25+
│ └── xml_value.rb # XML value handling
26+
├── spec/
27+
│ ├── chef-gyoku_spec.rb # Main gem specs
28+
│ ├── spec_helper.rb # Test configuration
29+
│ └── chef-gyoku/
30+
│ ├── array_spec.rb # Array conversion tests
31+
│ ├── hash_spec.rb # Hash conversion tests
32+
│ ├── prettifier_spec.rb # Prettifier tests
33+
│ ├── xml_key_spec.rb # XML key tests
34+
│ └── xml_value_spec.rb # XML value tests
35+
├── chef-gyoku.gemspec # Gem specification
36+
├── Gemfile # Dependencies
37+
├── Rakefile # Build and test tasks
38+
├── README.md # Documentation
39+
├── CHANGELOG.md # Version history
40+
├── MIT-LICENSE # License file
41+
└── .rubocop.yml # Code style configuration
42+
```
43+
44+
## Development Workflow
45+
46+
### 1. Jira Integration with MCP Server
47+
48+
When a Jira ID is provided in tasks:
49+
50+
1. **Fetch Jira Issue Details**: Use the `atlassian-mcp-server` MCP server to fetch Jira issue details
51+
```
52+
Use the mcp_atlassian-mcp_getJiraIssue tool with:
53+
- cloudId: Use mcp_atlassian-mcp_getAccessibleAtlassianResources to get the cloud ID first
54+
- issueIdOrKey: The provided Jira ID
55+
```
56+
57+
2. **Read and Analyze**: Carefully read the story description, acceptance criteria, and any technical requirements
58+
59+
3. **Plan Implementation**: Break down the task into actionable steps based on the Jira requirements
60+
61+
### 2. Implementation Standards
62+
63+
#### Code Quality Requirements
64+
- **Test Coverage**: Maintain > 80% test coverage at all times
65+
- **Code Style**: Follow Cookstyle standards (runs on CI via `cookstyle --chefstyle -c .rubocop.yml`)
66+
- **Ruby Version**: Support Ruby 3.1+ as specified in gemspec
67+
- **Dependencies**: Use only approved dependencies listed in gemspec
68+
69+
#### Testing Requirements
70+
- Write comprehensive unit tests for all new functionality
71+
- Use RSpec for testing framework
72+
- Place tests in appropriate `spec/` subdirectories matching `lib/` structure
73+
- Run tests with: `bundle exec rake spec`
74+
- Coverage reports generated via SimpleCov and Coveralls
75+
76+
### 3. DCO Compliance
77+
78+
**All commits MUST be signed off for Developer Certificate of Origin (DCO) compliance.**
79+
80+
#### DCO Requirements:
81+
- Every commit must include a `Signed-off-by` line
82+
- Use: `git commit -s -m "Your commit message"`
83+
- The sign-off certifies you have the right to submit the code under the project's license
84+
- Format: `Signed-off-by: Your Name <[email protected]>`
85+
86+
#### Example DCO-compliant commit:
87+
```bash
88+
git commit -s -m "Add XML namespace support for nested hashes
89+
90+
This implementation adds support for XML namespaces in nested hash
91+
structures as requested in JIRA-1234.
92+
93+
Signed-off-by: Developer Name <[email protected]>"
94+
```
95+
96+
### 4. GitHub Workflows and CI/CD
97+
98+
The repository uses GitHub Actions workflows:
99+
100+
#### CI Pipeline (`ci.yml`):
101+
- **Trigger**: Push to master, all PRs
102+
- **Ruby Versions**: 3.1, 3.4
103+
- **Steps**: Checkout → Setup Ruby → Bundle install → Run tests
104+
- **Coverage**: Coveralls integration for coverage reporting
105+
106+
#### Linting (`lint.yml`):
107+
- **Trigger**: PRs and push to main
108+
- **Tool**: Cookstyle with Chef style guide
109+
- **Configuration**: Uses `.rubocop.yml`
110+
- **Problem Matchers**: Shows failures directly in PR
111+
112+
### 5. Available GitHub Labels
113+
114+
Use these labels when creating PRs or issues:
115+
116+
| Label | Description | Use Case |
117+
|-------|-------------|----------|
118+
| `bug` | Something isn't working | Bug fixes and error corrections |
119+
| `documentation` | Improvements or additions to documentation | README updates, code comments |
120+
| `duplicate` | This issue or pull request already exists | Mark duplicates |
121+
| `enhancement` | New feature or request | New features and improvements |
122+
| `good first issue` | Good for newcomers | Beginner-friendly tasks |
123+
| `help wanted` | Extra attention is needed | Complex issues needing collaboration |
124+
| `invalid` | This doesn't seem right | Invalid or malformed issues |
125+
| `oss-standards` | Related to OSS Repository Standardization | Chef OSS compliance work |
126+
| `question` | Further information is requested | Clarifications needed |
127+
| `wontfix` | This will not be worked on | Rejected changes |
128+
129+
### 6. Pull Request Workflow
130+
131+
#### Branch Creation and PR Process:
132+
1. **Branch Naming**: Use the Jira ID as the branch name (e.g., `CHEF-1234`)
133+
2. **Create Branch**:
134+
```bash
135+
git checkout -b CHEF-1234
136+
```
137+
3. **Make Changes**: Implement the required functionality
138+
4. **Commit with DCO**:
139+
```bash
140+
git commit -s -m "Your detailed commit message"
141+
```
142+
5. **Push Branch**:
143+
```bash
144+
git push origin CHEF-1234
145+
```
146+
6. **Create PR using GH CLI**:
147+
```bash
148+
gh pr create --title "CHEF-1234: Brief description" --body "$(cat pr_description.html)"
149+
```
150+
151+
#### PR Description Format:
152+
Use Markdown formatting for PR descriptions:
153+
154+
```markdown
155+
## Summary
156+
Brief description of changes made.
157+
158+
## Changes Made
159+
- Added XML namespace support for nested hashes
160+
- Updated hash conversion logic in `lib/chef-gyoku/hash.rb`
161+
- Added comprehensive test coverage in `spec/chef-gyoku/hash_spec.rb`
162+
163+
## Testing
164+
- All existing tests pass
165+
- New tests added for namespace functionality
166+
- Coverage maintained above 80%
167+
168+
## Jira Issue
169+
Resolves: [CHEF-1234](https://issues.chef.io/browse/CHEF-1234)
170+
171+
## DCO
172+
All commits signed off with DCO compliance.
173+
174+
This work was completed with AI assistance following Progress AI policies.
175+
```
176+
177+
### 7. Prompt-Based Development Process
178+
179+
#### Step-by-Step Workflow:
180+
All tasks should follow this prompt-based approach:
181+
182+
1. **Initial Analysis**
183+
- Read Jira issue (if provided)
184+
- Analyze requirements
185+
- **Prompt**: "I have analyzed the requirements. The task involves [brief description]. Should I proceed with planning the implementation?"
186+
187+
2. **Implementation Planning**
188+
- Break down into subtasks
189+
- Identify files to modify/create
190+
- Plan test strategy
191+
- **Prompt**: "I have created an implementation plan with [X] steps: [list steps]. Should I proceed with step 1: [first step]?"
192+
193+
3. **Step-by-Step Implementation**
194+
- Complete one logical unit at a time
195+
- After each step: **Prompt**: "Step [N] completed: [what was done]. Next step is: [next step description]. Should I continue with the next step?"
196+
197+
4. **Testing Phase**
198+
- Write/update tests
199+
- Verify coverage
200+
- **Prompt**: "Implementation completed. Tests written and coverage verified at [X]%. Should I proceed with creating the PR?"
201+
202+
5. **PR Creation**
203+
- Create branch using Jira ID
204+
- Commit with DCO
205+
- Create PR with HTML description
206+
- **Prompt**: "PR created successfully: [PR link]. All tasks completed. Is there anything else you'd like me to do?"
207+
208+
#### Confirmation Requirements:
209+
- Always ask for confirmation before proceeding to the next major step
210+
- Provide clear summaries of what was accomplished
211+
- Indicate remaining steps in the workflow
212+
- Wait for explicit approval before continuing
213+
214+
### 8. Files and Areas to Avoid Modifying
215+
216+
**DO NOT MODIFY** these files without explicit approval:
217+
- `.github/workflows/` (CI/CD configurations)
218+
- `chef-gyoku.gemspec` (gem specification)
219+
- `Gemfile` (dependencies)
220+
- `.rubocop.yml` (style configuration)
221+
- `MIT-LICENSE` (license file)
222+
- Version files without proper versioning strategy
223+
224+
### 9. Testing and Quality Assurance
225+
226+
#### Before Creating PR:
227+
1. **Run Full Test Suite**:
228+
```bash
229+
bundle exec rake spec
230+
```
231+
2. **Check Code Style**:
232+
```bash
233+
bundle exec rake style
234+
```
235+
3. **Verify Coverage**: Ensure coverage remains > 80%
236+
4. **Manual Testing**: Test the specific functionality implemented
237+
238+
#### Test Structure:
239+
- Unit tests for all public methods
240+
- Edge case testing for XML generation
241+
- Integration tests for complex scenarios
242+
- Performance tests for large data structures (when applicable)
243+
244+
### 10. Additional Considerations
245+
246+
#### Ruby-Specific Guidelines:
247+
- Follow Ruby best practices and idioms
248+
- Use appropriate Ruby stdlib methods
249+
- Consider backward compatibility with supported Ruby versions
250+
- Handle encoding properly for XML generation
251+
252+
#### XML Processing Guidelines:
253+
- Validate XML output format
254+
- Handle special characters and escaping
255+
- Test namespace support thoroughly
256+
- Consider XML schema compliance where applicable
257+
258+
#### Documentation Updates:
259+
- Update README.md for new features
260+
- Add inline code documentation
261+
- Update CHANGELOG.md following semantic versioning
262+
- Include usage examples for complex features
263+
264+
## AI-Assisted Development & Compliance
265+
266+
- ✅ Create PR with `ai-assisted` label (if label doesn't exist, create it with description "Work completed with AI assistance following Progress AI policies" and color "9A4DFF")
267+
- ✅ Include "This work was completed with AI assistance following Progress AI policies" in PR description
268+
269+
### Jira Ticket Updates (MANDATORY)
270+
271+
- ✅ **IMMEDIATELY after PR creation**: Update Jira ticket custom field `customfield_11170` ("Does this Work Include AI Assisted Code?") to "Yes"
272+
- ✅ Use atlassian-mcp tools to update the Jira field programmatically
273+
- ✅ **CRITICAL**: Use correct field format: `{"customfield_11170": {"value": "Yes"}}`
274+
- ✅ Verify the field update was successful
275+
276+
### Documentation Requirements
277+
278+
- ✅ Reference AI assistance in commit messages where appropriate
279+
- ✅ Document any AI-generated code patterns or approaches in PR description
280+
- ✅ Maintain transparency about which parts were AI-assisted vs manual implementation
281+
282+
### Workflow Integration
283+
284+
This AI compliance checklist should be integrated into the main development workflow Step 4 (Pull Request Creation):
285+
286+
```
287+
Step 4: Pull Request Creation & AI Compliance
288+
- Step 4.1: Create branch and commit changes WITH SIGNED-OFF COMMITS
289+
- Step 4.2: Push changes to remote
290+
- Step 4.3: Create PR with ai-assisted label
291+
- Step 4.4: IMMEDIATELY update Jira customfield_11170 to "Yes"
292+
- Step 4.5: Verify both PR labels and Jira field are properly set
293+
- Step 4.6: Provide complete summary including AI compliance confirmation
294+
```
295+
296+
- **Never skip Jira field updates** - This is required for Progress AI governance
297+
- **Always verify updates succeeded** - Check response from atlassian-mcp tools
298+
- **Treat as atomic operation** - PR creation and Jira updates should happen together
299+
- **Double-check before final summary** - Confirm all AI compliance items are completed
300+
301+
### Audit Trail
302+
303+
All AI-assisted work must be traceable through:
304+
305+
1. GitHub PR labels (`ai-assisted`)
306+
2. Jira custom field (`customfield_11170` = "Yes")
307+
3. PR descriptions mentioning AI assistance
308+
4. Commit messages where relevant
309+
310+
---
311+
312+
This workflow ensures consistent, high-quality contributions to the chef-gyoku repository while maintaining compliance with Chef's development standards and processes.
313+
314+
Remember to always ask for confirmation before proceeding to the next step, and provide clear summaries of completed work and remaining tasks.

‎.vscode/mcp.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"servers": {
3+
"atlassian-mcp-server": {
4+
"url": "https://mcp.atlassian.com/v1/sse",
5+
"type": "http"
6+
}
7+
},
8+
"inputs": []
9+
}

0 commit comments

Comments
 (0)