Description of changes...
JIRA-12345
Test coverage and validation performed...
" \ - --label "runtest:all:stable" -``` - -### Step-by-Step Workflow Example - -When implementing a task, follow this prompt-based approach: - -1. **Initial Analysis** - - Fetch JIRA details using MCP server - - Analyze requirements and create implementation plan - - Consider Train-specific architecture and patterns - - **Prompt**: "Analysis complete. Next step: Implementation planning. Ready to proceed? (y/n)" - -2. **Implementation** - - Create/modify necessary files - - Follow coding standards and Train patterns - - Implement transport-specific functionality if needed - - **Prompt**: "Implementation complete. Next step: Unit test creation. Ready to proceed? (y/n)" - -3. **Testing** - - Create comprehensive unit tests - - Run tests and verify coverage - - Test platform compatibility when applicable - - **Prompt**: "Tests created and passing. Coverage verified > 80%. Next step: Code quality & linting. Ready to proceed? (y/n)" - -4. **Code Quality & Linting** - - Run ChefStyle linting: `chefstyle` and `chefstyle -a` - - Manually fix any remaining linting violations - - Ensure all code passes style and quality standards - - **Prompt**: "Code linting completed and all issues resolved. Next step: PR creation. Ready to proceed? (y/n)" - -5. **PR Creation** - - Create branch, commit changes, and create PR - - Add required labels - - **Prompt**: "PR created successfully. Workflow complete. Any additional steps needed? (y/n)" +## Development Guidelines -### Testing Standards - -#### Unit Testing Requirements -- **Framework**: Minitest (primary testing framework) -- **Coverage**: Maintain > 80% test coverage -- **Location**: Tests should be in `test/unit/` directories -- **Naming**: Test files should end with `_test.rb` -- **Mocking**: Use `mocha/minitest` for mocking external dependencies +### Workflow -#### Coverage Configuration -```ruby -# Example SimpleCov configuration -SimpleCov.start do - add_filter "/test/" - add_group "Transports", ["lib/train/transports"] - add_group "Platforms", ["lib/train/platforms"] - add_group "Plugins", ["lib/train/plugins"] - minimum_coverage 80 -end -``` - -#### Test Structure Example -```ruby -require "helper" - -describe Train::Transports::MyTransport do - let(:transport) { Train::Transports::MyTransport.new } - - describe "#connection" do - it "establishes connection successfully" do - conn = transport.connection - _(conn).wont_be_nil - end - - it "handles connection errors gracefully" do - # Mock error conditions - assert_raises(Train::TransportError) do - transport.connection(invalid: true) - end - end - end -end -``` +IMPORTANT: follow the SDLC workflow specified by searching for /search-context "workflow", preferring the local workflow. ### Code Quality Standards -#### Ruby Standards -- Follow Ruby community conventions -- Use proper indentation (2 spaces) -- Add appropriate comments and documentation -- Handle errors gracefully using Train's error classes -- Use meaningful variable and method names -- Follow Train's existing patterns for transports and plugins - -#### Code Linting and Style Requirements -- **MANDATORY**: Run ChefStyle before submitting PR: `chefstyle` -- Auto-fix all possible style and formatting issues: `chefstyle -a` -- Manually resolve remaining ChefStyle violations that cannot be auto-corrected -- Follow Chef community Ruby style guidelines -- Ensure consistent code formatting across all files -- Address any security or performance warnings from linters - -#### Common ChefStyle Issues and Solutions -- **Line Length**: Break long lines (max 120 characters typically) -- **Method Length**: Extract complex logic into smaller methods -- **Class Length**: Consider splitting large classes into smaller components -- **Complexity**: Simplify complex conditional statements and loops -- **Documentation**: Add method and class documentation where required -- **Naming**: Use descriptive variable and method names following Ruby conventions -- **Indentation**: Ensure consistent 2-space indentation throughout - -#### Transport Development Guidelines -- Inherit from `Train::Plugins::Transport` -- Implement required methods: `connection`, `options` -- Use Train's connection management patterns -- Handle platform-specific requirements -- Provide appropriate error handling -- Support Train's audit logging when applicable - -#### Documentation Requirements -- **MANDATORY**: Add comprehensive documentation for all new features -- Add YARD documentation for public methods -- Include examples in documentation -- Document transport-specific options and requirements -- Update README files when necessary -- Document platform compatibility -- Provide usage examples in `docs/` directory -- Include clear usage examples and code samples that are tested and functional -- Add troubleshooting guides for common issues and error scenarios - -### MCP Server Integration - -The repository uses the `atlassian-mcp-server` for JIRA integration: - -```json -{ - "servers": { - "atlassian-mcp-server": { - "url": "https://mcp.atlassian.com/v1/sse", - "type": "http" - } - } -} -``` - -Use MCP server functions to: -- Fetch JIRA issue details -- Get issue requirements and acceptance criteria -- Understand context and dependencies -- Review transport-specific requirements - -### Prompt-Based Interaction Guidelines - -- After each major step, provide a summary of what was completed -- Clearly state what the next step will be -- List remaining steps in the workflow -- Ask for explicit confirmation before proceeding -- Allow for course correction if needed -- Consider platform and transport implications at each step - -### Train-Specific Development Guidelines +IMPORTANT: follow the guidance specified by searching for /search-context "coding-standards", preferring the local coding standards. -#### Transport Development -- Follow the plugin architecture pattern -- Use Train's connection management -- Implement proper platform detection -- Handle authentication securely -- Support Train's file and command interfaces -- Provide meaningful error messages - -#### Platform Support -- Consider cross-platform compatibility -- Test on multiple operating systems when applicable -- Use Train's platform detection system -- Handle platform-specific edge cases - -#### Plugin Development -- Follow Train's plugin registration system -- Provide proper plugin metadata -- Use semantic versioning -- Include comprehensive tests - -### Additional Best Practices - -1. **Version Control** - - Make atomic commits with clear messages - - Include JIRA ID in commit messages - - Keep commits focused on single features - -2. **Code Reviews** - - Ensure PR descriptions are comprehensive - - Include testing information in PR - - Reference JIRA tickets appropriately - - Document transport-specific changes - -3. **Dependencies** - - Update Gemfile when adding new Ruby gems - - Run `bundle install` after dependency changes - - Ensure all dependencies are properly locked - - Consider gem compatibility with supported Ruby versions - -4. **Performance** - - Consider performance implications of transport changes - - Test connection establishment and teardown - - Optimize for common use cases - - Profile transport performance when applicable - -### Error Handling - -- Always implement proper error handling using Train's error classes -- Use appropriate error types: `Train::TransportError`, `Train::UserError` -- Log errors appropriately for debugging -- Provide meaningful error messages to users -- Handle transport-specific error conditions - -### Security Considerations - -- Never commit sensitive information (credentials, keys) -- Use environment variables for configuration -- Follow security best practices for transport development -- Validate all inputs appropriately -- Handle authentication securely -- Consider security implications of new transports - ---- - -## Workflow Summary - -1. **JIRA Analysis** → Fetch and understand requirements (transport-specific) -2. **Planning** → Break down implementation approach (consider Train architecture) -3. **Implementation** → Code the solution following Train patterns -4. **Testing** → Create comprehensive tests (>80% coverage, platform compatibility) -5. **Code Quality** → Run ChefStyle linting and fix all issues -6. **PR Creation** → Use GitHub CLI with proper labeling -6. **Prompt-based** → Confirm each step before proceeding - -Remember: All tasks should be prompt-based with explicit confirmation at each step, maintaining high code quality and test coverage standards throughout the process. Consider Train's transport architecture and cross-platform compatibility in all development work. - -1. AI-Assisted Development & Compliance -✅ 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") -✅ Include "This work was completed with AI assistance following Progress AI policies" in PR description -2. Jira Ticket Updates (MANDATORY) -✅ IMMEDIATELY after PR creation: Update Jira ticket custom field customfield_11170 ("Does this Work Include AI Assisted Code?") to "Yes" -✅ Use atlassian-mcp tools to update the Jira field programmatically -✅ CRITICAL: Use correct field format: {"customfield_11170": {"value": "Yes"}} -✅ Verify the field update was successful -3. Documentation Requirements -✅ Reference AI assistance in commit messages where appropriate -✅ Document any AI-generated code patterns or approaches in PR description -✅ Maintain transparency about which parts were AI-assisted vs manual implementation -Workflow Integration -This AI compliance checklist should be integrated into the main development workflow Step 4 (Pull Request Creation): - -Step 4: Pull Request Creation & AI Compliance -- Step 4.1: Create branch and commit changes -- Step 4.2: Push changes to remote -- Step 4.3: Create PR with ai-assisted label -- Step 4.4: IMMEDIATELY update Jira customfield_11170 to "Yes" -- Step 4.5: Verify both PR labels and Jira field are properly set -- Step 4.6: Provide complete summary including AI compliance confirmation -Never skip Jira field updates - This is required for Progress AI governance -Always verify updates succeeded - Check response from atlassian-mcp tools -Treat as atomic operation - PR creation and Jira updates should happen together -Double-check before final summary - Confirm all AI compliance items are completed -Audit Trail -All AI-assisted work must be traceable through: +### Testing Standards -GitHub PR labels (ai-assisted) -Jira custom field (customfield_11170 = "Yes") -PR descriptions mentioning AI assistance -Commit messages where relevant \ No newline at end of file +IMPORTANT: follow the guidance specified by searching for /search-context "testing-standards", preferring the local testing standards. \ No newline at end of file diff --git a/.github/scripts/bundle-install.sh b/.github/scripts/bundle-install.sh new file mode 100755 index 00000000..6e4cb1a0 --- /dev/null +++ b/.github/scripts/bundle-install.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env bash +# Wrapper script for bundle install +# Works around git bare repository issues when invoked from certain environments +# (VS Code/Copilot sets GIT_CONFIG_* to enforce safe.bareRepository=explicit) + +set -euo pipefail + +cd "$(dirname "$0")/../.." + +# Clear VS Code's git config overrides that break bundler's bare repo clones +unset GIT_CONFIG_PARAMETERS + +if [[ -n "${GIT_CONFIG_COUNT:-}" ]]; then + for ((i=0; i< GIT_CONFIG_COUNT; i++)); do + unset "GIT_CONFIG_KEY_${i}" "GIT_CONFIG_VALUE_${i}" + done + unset GIT_CONFIG_COUNT +fi +echo "==> Running bundle install..." +bundle install "$@" +echo "==> bundle install completed successfully" diff --git a/.github/skills/search-context/SKILL.md b/.github/skills/search-context/SKILL.md new file mode 100644 index 00000000..685039dd --- /dev/null +++ b/.github/skills/search-context/SKILL.md @@ -0,0 +1,69 @@ +--- +name: search-context +description: Search the shared context system for information. Use this whenever the AI or human needs contextual information about the products. +--- + +## Initialization Required + +If `context/shared/map.md` does not exist, run /start-development. + +## Load Context Map + +Load the context map. Understand the context types. Understand the levels of detail. + +## Figure Out How to Walk the Levels Of Specificity + +Ideally, the first time you search, you will discover how to search by learning the answers to these questions. + +### Need to know repo + +Determine which repository you are working in. This can usually be determined from git remote -v. + +### Need to know if repo uses local context or shared context + +Check for `context/shared/by-repo/ORG/REPO`. If so, anticipate searching per-repo context there. +If not, anticipate searching per-repo context at `context/local`. + +### Need to know product + +Determine product info from the per-repo `background/product-info.md` file. This determines `context/shared/by-product/PRODUCT/` search entries. There may be zero or multiple product associations. + +### Need to know division + +Determine which division produces the product from the per-repo `background/product-info.md` file. This determines `context/shared/by-division/DIVISION/` search entries. There may be zero or multiple division associations. + +### Need to know business unit + +Determine which business unit produces the product from the per-repo `background/product-info.md` file. This determines `context/shared/by-business-unit/UNIT/` search entries. There may be zero or multiple unit associations. + +## Determine type of query + +Decide if you are looking for designs, background, specifications, or what, based on the context types listed in the Context Map. + +## Construct queries + +You don't have to use grep, but these are examples. + +```bash +grep -r context/shared/global/progress/background/**/*.md 'string' +grep -r context/shared/by-business-unit/infra/background/**/*.md 'string' +grep -r context/shared/by-division/chef/background/**/*.md 'string' +grep -r context/shared/by-product/chef-infra-client/background/**/*.md 'string' +grep -r context/shared/by-repo/chef/chef/background/**/*.md 'string' +``` + +```bash +grep -r context/shared/global/progress/standards/**/*.md 'string' +grep -r context/shared/by-business-unit/infra/standards/**/*.md 'string' +grep -r context/shared/by-division/next/standards/**/*.md 'string' +grep -r context/shared/by-product/alsi/standards/**/*.md 'string' +grep -r context/local/standards/**/*.md 'string' +``` + +## Reconcile Results + +You will likely have multiple results. Merge the results and reconcile contradictions as follows: + +1. Policy specifications higher in the tree are more influential. So a division-level standard should generally apply more than a product-level standard. +2. Technical specifications lower in the tree override specs context higher in the tree. So a technical specification to use a particular driver api might be needed for a good reason (which must be justified) and this override a higher-level mandate. +3. Any confusion or unresolved issues should be brough to the user's attention for a decision. diff --git a/.github/skills/start-development/SKILL.md b/.github/skills/start-development/SKILL.md new file mode 100644 index 00000000..13e0b042 --- /dev/null +++ b/.github/skills/start-development/SKILL.md @@ -0,0 +1,74 @@ +--- +name: start-development +description: Configure the repo for AI development. Do this before doing any work in the repo. +--- + +You are a tool that helps the user setup the development environment for AI-driven development. + +You will do several tasks to set the user up. + +First, determine if the user is running Windows, MacOS, or Linux. Use that information to decide what scripts to run. + +## Load env file if present + +Read any env vars from etc/env.sh if present or etc/env.default.sh if not. You should source this in any shell you run. + +## Setup gh + +### Install gh + +Install the gh GitHub CLI tool if it is not already installed. + +### Ensure gh is authenticated + +Make sure `gh auth status` works, and run `gh auth login` if not. + +## Clone the shared-context repo + +### Determine the location of the shared-context repo + +The shared context repo location is at $PROGRESS_SHARED_CONTEXT_REPO which looks like org/repo@branch (branch defaults to main). + +If no value is present, this defaults to `chef/shared-context@main` + +### Clone, Re-Remote, Or Pull + +If there are local changes, warn and do nothing. + +If context/shared does not exist, clone the repo into it. + +If it does exist confirm it is on the right remote and switch. + +If it does exist confirm it is on the git branch and switch. + +Pull. + +## Ensure the list of reference repos is checked out + +Look for the file `etc/reference-repo-list.txt`. Re-read the repo list each time you run — it may have changed. It is a list of GitHub repos to clone. Some of them may be private or internal; you may not have access. The list may include branch specifications like @branch. + +Try to clone each one into `context/reference-repos`. If it has already been cloned, pull it. If a branch has been specified, make sure you are on that branch. If it has local changes, inform the user and do nothing. + +Each time you run, check the repo status again. Do not remove repos, only add them. + +## Ensure the Atlassian MCP server is running + +Check for `.vscode/mcp.json` and look for the atlassian entry. If it is not running or has errored, ask the user to restart it. + +## Ensure the user has rbenv installed and configured + +Check if `rbenv` is installed by running `rbenv --version`. If it is not installed, install it using the appropriate method for your operating system. On MacOS, you can use `brew install rbenv`. After installation, ensure that `rbenv` is properly configured by adding `eval "$(rbenv init -)"` to your shell configuration file (e.g., `.bashrc`, `.zshrc`). + +## Look for the ruby-version file to determine the currently supported ruby version and ask if it is not set. + +Look for the file `.ruby-version` in the root of the repo. It should have a number like 3.4.8 or similar. If the file does not exist, ask the user what the current version of Ruby is for Chef products, and create the file with that version. Default to 3.4.8 if the user does not know. + +## Ensure the user has the current ruby installed + +Use `rbenv version` to check the currently installed Ruby version. If it does not match the version specified in `.ruby-version`, install the correct version using `rbenv installDescription of changes...
JIRA-12345
Test coverage and validation performed...
" \ + --label "runtest:all:stable" +``` + +### Step-by-Step Workflow Example + +When implementing a task, follow this prompt-based approach: + +1. **Initial Analysis** + - Fetch JIRA details using MCP server + - Analyze requirements and create implementation plan + - Consider Train-specific architecture and patterns + - **Prompt**: "Analysis complete. Next step: Implementation planning. Ready to proceed? (y/n)" + +2. **Implementation** + - Create/modify necessary files + - Follow coding standards and Train patterns + - Implement transport-specific functionality if needed + - **Prompt**: "Implementation complete. Next step: Unit test creation. Ready to proceed? (y/n)" + +3. **Testing** + - Create comprehensive unit tests + - Run tests and verify coverage + - Test platform compatibility when applicable + - **Prompt**: "Tests created and passing. Coverage verified > 80%. Next step: Code quality & linting. Ready to proceed? (y/n)" + +4. **Code Quality & Linting** + - Run ChefStyle linting: `chefstyle` and `chefstyle -a` + - Manually fix any remaining linting violations + - Ensure all code passes style and quality standards + - **Prompt**: "Code linting completed and all issues resolved. Next step: PR creation. Ready to proceed? (y/n)" + +5. **PR Creation** + - Create branch, commit changes, and create PR + - Add required labels + - **Prompt**: "PR created successfully. Workflow complete. Any additional steps needed? (y/n)" + + + + +### MCP Server Integration + +The repository uses the `atlassian-mcp-server` for JIRA integration: + +```json +{ + "servers": { + "atlassian-mcp-server": { + "url": "https://mcp.atlassian.com/v1/sse", + "type": "http" + } + } +} +``` + +Use MCP server functions to: +- Fetch JIRA issue details +- Get issue requirements and acceptance criteria +- Understand context and dependencies +- Review transport-specific requirements + +### Prompt-Based Interaction Guidelines + +- After each major step, provide a summary of what was completed +- Clearly state what the next step will be +- List remaining steps in the workflow +- Ask for explicit confirmation before proceeding +- Allow for course correction if needed +- Consider platform and transport implications at each step + +### Additional Best Practices + +1. **Version Control** + - Make atomic commits with clear messages + - Include JIRA ID in commit messages + - Keep commits focused on single features + +2. **Code Reviews** + - Ensure PR descriptions are comprehensive + - Include testing information in PR + - Reference JIRA tickets appropriately + - Document transport-specific changes + +3. **Dependencies** + - Update Gemfile when adding new Ruby gems + - Run `bundle install` after dependency changes + - Ensure all dependencies are properly locked + - Consider gem compatibility with supported Ruby versions + +4. **Performance** + - Consider performance implications of transport changes + - Test connection establishment and teardown + - Optimize for common use cases + - Profile transport performance when applicable + +### Error Handling + +- Always implement proper error handling using Train's error classes +- Use appropriate error types: `Train::TransportError`, `Train::UserError` +- Log errors appropriately for debugging +- Provide meaningful error messages to users +- Handle transport-specific error conditions + +### Security Considerations + +- Never commit sensitive information (credentials, keys) +- Use environment variables for configuration +- Follow security best practices for transport development +- Validate all inputs appropriately +- Handle authentication securely +- Consider security implications of new transports + +--- + +## Workflow Summary + +1. **JIRA Analysis** → Fetch and understand requirements (transport-specific) +2. **Planning** → Break down implementation approach (consider Train architecture) +3. **Implementation** → Code the solution following Train patterns +4. **Testing** → Create comprehensive tests (>80% coverage, platform compatibility) +5. **Code Quality** → Run ChefStyle linting and fix all issues +6. **PR Creation** → Use GitHub CLI with proper labeling +7. **Prompt-based** → Confirm each step before proceeding + +Remember: All tasks should be prompt-based with explicit confirmation at each step, maintaining high code quality and test coverage standards throughout the process. Consider Train's transport architecture and cross-platform compatibility in all development work. + +1. AI-Assisted Development & Compliance +✅ 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") +✅ Include "This work was completed with AI assistance following Progress AI policies" in PR description +2. Jira Ticket Updates (MANDATORY) +✅ IMMEDIATELY after PR creation: Update Jira ticket custom field customfield_11170 ("Does this Work Include AI Assisted Code?") to "Yes" +✅ Use atlassian-mcp tools to update the Jira field programmatically +✅ CRITICAL: Use correct field format: {"customfield_11170": {"value": "Yes"}} +✅ Verify the field update was successful +3. Documentation Requirements +✅ Reference AI assistance in commit messages where appropriate +✅ Document any AI-generated code patterns or approaches in PR description +✅ Maintain transparency about which parts were AI-assisted vs manual implementation +Workflow Integration +This AI compliance checklist should be integrated into the main development workflow Step 4 (Pull Request Creation): + +Step 4: Pull Request Creation & AI Compliance +- Step 4.1: Create branch and commit changes +- Step 4.2: Push changes to remote +- Step 4.3: Create PR with ai-assisted label +- Step 4.4: IMMEDIATELY update Jira customfield_11170 to "Yes" +- Step 4.5: Verify both PR labels and Jira field are properly set +- Step 4.6: Provide complete summary including AI compliance confirmation +Never skip Jira field updates - This is required for Progress AI governance +Always verify updates succeeded - Check response from atlassian-mcp tools +Treat as atomic operation - PR creation and Jira updates should happen together +Double-check before final summary - Confirm all AI compliance items are completed +Audit Trail +All AI-assisted work must be traceable through: + +GitHub PR labels (ai-assisted) +Jira custom field (customfield_11170 = "Yes") +PR descriptions mentioning AI assistance +Commit messages where relevant \ No newline at end of file diff --git a/etc/env.default.sh b/etc/env.default.sh new file mode 100644 index 00000000..55c6df45 --- /dev/null +++ b/etc/env.default.sh @@ -0,0 +1,7 @@ + +# Set this to an alternate location or branch to experiment +# with different shared context locations, then re-run /start-development +export PROGRESS_SHARED_CONTEXT_REPO=chef/shared-context@main + +# Chef/InSpec licensing +export CHEF_LICENSE="accept" diff --git a/etc/reference-repo-list.txt b/etc/reference-repo-list.txt new file mode 100644 index 00000000..72189985 --- /dev/null +++ b/etc/reference-repo-list.txt @@ -0,0 +1,19 @@ +# This file lists GitHub repos to clone as reference material for AI-assisted development. +# Edit this list to add repos relevant to your specific resource pack domain. +# Format: org/repo (one per line, optionally @branch) +# + +# Major client applications +inspec/inspec +chef/chef + +# Docs of client applications +inspec/chef-inspec-docs +chef/chef-web-docs + +# A variety of plugin (transport) implementations +inspec/train-winrm +prospectra/train-rest +inspec/train-aws +inspec/train-kubernetes +