Merge branch 'main' into design-and-docs

Author: eleanorjboyd

.github/instructions/generic.instructions.md

@@ -0,0 +1,32 @@
+---
+applyTo: '**'
+---
+
+Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.# Coding Instructions for vscode-python-environments
+
+## Localization
+
+-   Localize all user-facing messages using VS Code’s `l10n` API.
+-   Internal log messages do not require localization.
+
+## Logging
+
+-   Use the extension’s logging utilities (`traceLog`, `traceVerbose`) for internal logs.
+-   Do not use `console.log` or `console.warn` for logging.
+
+## Settings Precedence
+
+-   Always consider VS Code settings precedence:
+    1. Workspace folder
+    2. Workspace
+    3. User/global
+-   Remove or update settings from the highest precedence scope first.
+
+## Error Handling & User Notifications
+
+-   Avoid showing the same error message multiple times in a session; track state with a module-level variable.
+-   Use clear, actionable error messages and offer relevant buttons (e.g., "Open settings", "Close").
+
+## Documentation
+
+-   Add clear docstrings to public functions, describing their purpose, parameters, and behavior.

.github/instructions/issue-format.instructions.md

@@ -0,0 +1,84 @@
+---
+applyTo: '**/github-issues/**'
+---
+
+# Guidelines for Creating Effective GitHub Issues
+
+## Issue Format
+
+When creating GitHub issues, use the following structure to ensure clarity and ease of verification:
+
+### For Bug Reports
+
+1. **Title**: Concise description of the issue (5-10 words)
+
+2. **Problem Statement**:
+
+    - 1-2 sentences describing the issue
+    - Focus on user impact
+    - Use clear, non-technical language when possible
+
+3. **Steps to Verify Fix**:
+    - Numbered list (5-7 steps maximum)
+    - Start each step with an action verb
+    - Include expected observations
+    - Cover both success paths and cancellation/back button scenarios
+
+### For Feature Requests
+
+1. **Title**: Clear description of the requested feature
+
+2. **Need Statement**:
+
+    - 1-2 sentences describing the user need
+    - Explain why this feature would be valuable
+
+3. **Acceptance Criteria**:
+    - Bulleted list of verifiable behaviors
+    - Include how a user would confirm the feature works as expected
+
+## Examples
+
+### Bug Report Example
+
+```
+# Terminal opens prematurely with PET Resolve Environment command
+
+**Problem:** When using "Resolve Environment..." from the Python Environment Tool menu,
+the terminal opens before entering a path, creating a confusing workflow.
+
+**Steps to verify fix:**
+1. Run "Python Environments: Run Python Environment Tool in Terminal" from Command Palette
+2. Select "Resolve Environment..."
+3. Verify no terminal opens yet
+4. Enter a Python path
+5. Verify terminal only appears after path entry
+6. Try canceling at the input step - confirm no terminal appears
+```
+
+### Feature Request Example
+
+```
+# Add back button support to multi-step UI flows
+
+**Problem:** The UI flows for environment creation and Python project setup lack back button
+functionality, forcing users to cancel and restart when they need to change a previous selection.
+
+**Steps to verify implementation:**
+1. Test back button in PET workflow: Run "Python Environments: Run Python Environment Tool in Terminal",
+   select "Resolve Environment...", press back button, confirm it returns to menu
+2. Test back button in VENV creation: Run "Create environment", select VENV, press back button at various steps
+3. Test back button in CONDA creation: Create CONDA environment, use back buttons to navigate between steps
+4. Test back button in Python project flow: Add Python project, verify back functionality in project type selection
+```
+
+## Best Practices
+
+1. **Be concise**: Keep descriptions short but informative
+2. **Use active voice**: "Terminal opens prematurely" rather than "The terminal is opened prematurely"
+3. **Include context**: Mention relevant commands, UI elements, and workflows
+4. **Focus on verification**: Make steps actionable and observable
+5. **Cover edge cases**: Include cancellation paths and error scenarios
+6. **Use formatting**: Bold headings and numbered lists improve readability
+
+Remember that good issues help both developers fixing problems and testers verifying solutions.