Merge branch 'main' into prepared-harrier

Author: eleanorjboyd

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,81 @@
+---
+name: Bug Report
+about: Create a report to help us improve.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!--
+Please search existing issues first to avoid creating duplicates:
+https://github.com/microsoft/vscode-python-environments/issues
+-->
+
+## Environment data
+
+<!--
+To find extension versions, open the VS Code Extensions panel and locate each
+extension from the list of installed extensions. The version appears next to the name.
+-->
+
+-   Python Environments extension version: XXX
+-   Python extension (`ms-python.python`) version: XXX
+-   VS Code version (Help → About): XXX
+-   OS and version: XXX
+-   Python version (& distribution if applicable, e.g. Anaconda): XXX
+-   Environment manager in use (`venv` / `conda` / `pyenv` / `poetry` / `pipenv` / `system` / `uv` / other): XXX
+-   Shell (bash / zsh / fish / pwsh / cmd / other): XXX
+-   Remote / container scenario (none / WSL / SSH Remote / Dev Container / Codespaces): XXX
+-   Workspace type (single folder / multi-root / mono-repo): XXX
+-   Is this a regression? If yes, last known working extension version: XXX
+
+## Repro Steps
+
+<!--
+Please list the minimal steps needed to reproduce the issue, starting from a fresh
+VS Code window when possible. If the issue only reproduces with specific workspace
+contents (e.g. a `pyproject.toml`, `.venv`, `environment.yml`, `Pipfile`, `poetry.lock`,
+`.python-version`), please share a minimal example or describe the layout.
+
+If the bug only reproduces with certain settings, please include the relevant entries
+from your `settings.json` (user and/or workspace).
+-->
+
+1. XXX
+
+## Expected behavior
+
+XXX
+
+## Actual behavior
+
+XXX
+
+## Logs
+
+<!--
+Please include logs from the "Python Environments" output channel.
+
+To capture verbose logs:
+1. Open the Output panel (View → Output).
+2. Select "Python Environments" from the channel dropdown in the upper-right.
+3. Click the gear / filter icon at the top of the Output panel and set the level to "Trace".
+   (Alternatively: Command Palette → "Developer: Set Log Level…" → "Python Environments" → "Trace".)
+4. Reproduce the issue.
+5. Paste the relevant output below, or save it to a `.txt` file and attach it to the issue (preferred for long logs).
+
+If the issue is about terminal activation, please also paste the exact terminal
+output where the problem occurs.
+-->
+
+```
+XXX
+```
+
+## Additional context
+
+<!--
+Anything else that may help us reproduce: screenshots, videos, related issues,
+links to your project, workarounds you've tried, etc.
+-->

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,12 @@
+---
+name: Feature Request
+about: Suggest an idea for this project.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!-- Please search existing feature requests to avoid creating duplicates. -->
+
+<!-- Describe the feature you'd like. -->

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,19 @@
+---
+name: Question
+about: Ask a question about this project.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!--
+Please search existing issues to avoid creating duplicates.
+For general Python-in-VS-Code usage questions, consider starting a discussion at
+https://github.com/microsoft/vscode-python/discussions/categories/q-a
+or checking the issues in the following related repositories:
+- Python extension: https://github.com/microsoft/vscode-python/issues
+- Pylance: https://github.com/microsoft/pylance-release/issues
+- Jupyter: https://github.com/microsoft/vscode-jupyter/issues
+- Python Debugger: https://github.com/microsoft/vscode-python-debugger/issues
+-->

.github/hooks/scripts/stop_hook.py

@@ -110,13 +110,12 @@ def main() -> int:
         response = {
             "hookSpecificOutput": {
                 "hookEventName": "Stop",
-                "decision": "block",
+                "decision": "warn",
                 "reason": (
                     "You have uncommitted TypeScript changes. "
-                    "Before finishing, use the run-pre-commit-checks skill "
+                    "Before finishing, consider using the run-pre-commit-checks skill "
                     "or manually run: npm run lint && npm run compile-tests && npm run unittest. "
-                    "If checks pass and changes are ready, commit them. "
-                    "If this session is just research/exploration, you can proceed without committing."
+                    "Ask the user whether to commit or leave changes uncommitted."
                 ),
             }
         }
@@ -128,10 +127,10 @@ def main() -> int:
         response = {
             "hookSpecificOutput": {
                 "hookEventName": "Stop",
-                "decision": "block",
+                "decision": "warn",
                 "reason": (
                     "You have staged changes that haven't been committed. "
-                    "Either commit them with a proper message or unstage them before finishing."
+                    "Ask the user whether to commit them or leave them staged."
                 ),
             }
         }

package-lock.json

@@ -2,7 +2,7 @@
     "name": "vscode-python-envs",
     "displayName": "Python Environments",
     "description": "Provides a unified python environment experience",
-    "version": "1.28.0",
+    "version": "1.29.0",
     "publisher": "ms-python",
     "preview": true,
     "engines": {

package.json

@@ -343,6 +343,14 @@ export interface QuickCreateConfig {
 
 /**
  * Interface representing an environment manager.
+ *
+ * @remarks
+ * Methods on this interface are invoked both by the Python Environments extension itself
+ * (in response to UI actions, startup, terminal activation, script execution, and so on)
+ * and directly by other extensions that consume the published API. Any "called when…"
+ * notes on individual methods list representative triggers only — they are not
+ * exhaustive, and the precise set of call sites may evolve over time. Implementations
+ * should focus on the documented contract rather than any specific caller.
  */
 export interface EnvironmentManager {
     /**
@@ -396,27 +404,44 @@ export interface EnvironmentManager {
      * @param scope - The scope within which to create the environment.
      * @param options - Optional parameters for creating the Python environment.
      * @returns A promise that resolves to the created Python environment, or undefined if creation failed.
+     *
+     * @remarks
+     * Invoked when an environment of this manager's type should be created for the given
+     * scope. Typical triggers include user-initiated environment-creation flows and
+     * programmatic creation via the API.
      */
     create?(scope: CreateEnvironmentScope, options?: CreateEnvironmentOptions): Promise<PythonEnvironment | undefined>;
 
     /**
      * Removes the specified Python environment.
      * @param environment - The Python environment to remove.
      * @returns A promise that resolves when the environment is removed.
+     *
+     * @remarks
+     * Invoked to delete the given environment. Typical triggers include an explicit user
+     * action (such as a "Delete Environment" command) and programmatic removal via the API.
      */
     remove?(environment: PythonEnvironment): Promise<void>;
 
     /**
      * Refreshes the list of Python environments within the specified scope.
      * @param scope - The scope within which to refresh environments.
      * @returns A promise that resolves when the refresh is complete.
+     *
+     * @remarks
+     * Forces the manager to re-discover environments for the given scope. Typically
+     * triggered by an explicit user "refresh" action.
      */
     refresh(scope: RefreshEnvironmentsScope): Promise<void>;
 
     /**
      * Retrieves a list of Python environments within the specified scope.
      * @param scope - The scope within which to retrieve environments.
      * @returns A promise that resolves to an array of Python environments.
+     *
+     * @remarks
+     * Returns the environments known to this manager for the given scope. Called
+     * frequently by UI surfaces (tree views, pickers) and by other consumers of the API.
      */
     getEnvironments(scope: GetEnvironmentsScope): Promise<PythonEnvironment[]>;
 
@@ -430,13 +455,27 @@ export interface EnvironmentManager {
      * @param scope - The scope within which to set the environment.
      * @param environment - The Python environment to set. If undefined, the environment is unset.
      * @returns A promise that resolves when the environment is set.
+     *
+     * @remarks
+     * Invoked when the active environment for the given scope should change — for example
+     * after the user selects an environment in a picker, after a newly created environment
+     * is auto-selected, or programmatically via the API.
+     *
+     * Also invoked at extension startup to rehydrate the active environment from
+     * persisted state.
      */
     set(scope: SetEnvironmentScope, environment?: PythonEnvironment): Promise<void>;
 
     /**
      * Retrieves the current Python environment within the specified scope.
      * @param scope - The scope within which to retrieve the environment.
      * @returns A promise that resolves to the current Python environment, or undefined if none is set.
+     *
+     * @remarks
+     * Returns the currently active environment for the given scope, or `undefined` if
+     * none is selected. Called very frequently — at startup, after {@link set}, when a
+     * terminal is opened, before running Python, by UI surfaces that display the active
+     * interpreter, and by other extensions consuming the API.
      */
     get(scope: GetEnvironmentScope): Promise<PythonEnvironment | undefined>;
 
@@ -456,13 +495,27 @@ export interface EnvironmentManager {
      *
      * @param context - The context for resolving the environment, which can be a {@link PythonEnvironment} or a {@link Uri}.
      * @returns A promise that resolves to the fully detailed {@link PythonEnvironment}, or `undefined` if the environment cannot be resolved.
+     *
+     * @remarks
+     * Called to turn a lightly-populated {@link PythonEnvironment} or a {@link Uri}
+     * pointing at an interpreter or environment folder into a fully-populated
+     * {@link PythonEnvironment} with complete {@link PythonEnvironment.execInfo}. Typical
+     * triggers include the user manually selecting an interpreter path, resolving
+     * `python.defaultInterpreterPath` at startup, and populating execution details before
+     * launching Python.
      */
     resolve(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
 
     /**
      * Clears the environment manager's cache.
      *
      * @returns A promise that resolves when the cache is cleared.
+     *
+     * @remarks
+     * Drops any cached environment data held by the manager so that subsequent calls to
+     * {@link EnvironmentManager.getEnvironments} or {@link EnvironmentManager.get}
+     * re-discover state from disk. Typically triggered by an explicit user "clear cache"
+     * action.
      */
     clearCache?(): Promise<void>;
 }