Feature: Windows Python Default Setup Script

[NickLinney]

Feature: Windows Python Default Setup Script

Branch: feature/python-windows-default-setup
Base branch: release/0.4.0
Target release: v0.4.0 (MINOR feature addition)

---

Summary

Add a Windows-specific Python bootstrap script to the env repository that establishes a standards-aligned, repeatable Python development baseline on Windows systems.

This feature introduces a PowerShell script located at:

env/Python/Windows/python_default_setup.ps1

The script mirrors the intent and structure of the Debian 13 (“trixie”) setup while respecting Windows platform realities. It explicitly aligns with AD-2026-02-09-06 — Python Development Environment Standards, emphasizing:

• official Python releases
• pip + venv
• explicit interpreter selection
• minimal, auditable tooling
• no mandatory workflow abstractions

---

Motivation

• Windows is a primary developer workstation platform.
• Existing Windows setups are often inconsistent, manual, or tool-opinionated.
• The project already enforces conservative, standards-based Python workflows in CI.
• Debian now has a clean, documented Python bootstrap path.
• Windows parity is required before broader adoption and contributor onboarding.

This feature ensures Windows developers can reach the same canonical baseline as Linux and macOS without introducing divergent tooling or governance risk.

---

Scope (Minimal by Design)

This feature will add only what is necessary to:

• install and manage multiple official Python versions
• define a clear default interpreter
• ensure pip and venv work predictably
• document verification and expected behavior

Out of scope by design:

• Poetry
• uv
• project generators
• lockfile enforcement
• workflow orchestration tools

Local developer preferences remain optional and non-normative.

---

Deliverables

1. Directory Structure

env/
└─ Python/
   └─ Windows/
      ├─ README.md
      └─ python_default_setup.ps1

Structure follows established repo conventions:

• OS-scoped
• version-agnostic (Windows does not require distro codename scoping)
• future-proofed for extension

---

2. python_default_setup.ps1

Primary Windows bootstrap script.

Responsibilities:

• Detect or install official Python (via python.org installer or Windows Store-safe method)
• Ensure pip and venv availability
• Optionally install multiple Python versions (where supported)
• Establish a documented default Python interpreter
• Configure PATH idempotently at the user level
• Provide clear verification output

Configurable values at top of script:

• Python versions to install
• Default Python version
• Whether to modify user PATH
• Optional pipx installation (non-authoritative)

Non-Goals:

• No Poetry
• No enforced package manager alternatives
• No project scaffolding
• No deviation from canonical CI expectations

---

3. README.md (Windows)

Concise operator documentation covering:

• Purpose and scope

• Quick start (one-command PowerShell invocation)

• What “default Python” means on Windows

• How to:

  • verify installed versions
  • select a specific interpreter
  • create a venv explicitly

• Known Windows limitations and assumptions

Style:

• practical
• minimal
• human-oriented
• consistent with Debian/macOS READMEs

---

Behavioral Acceptance Criteria

On a fresh Windows system:

• Running python_default_setup.ps1 completes without manual intervention
• One or more official Python versions are installed
• A default Python version is clearly defined
• A user can successfully run:

python -m venv venv
.\venv\Scripts\Activate.ps1

• No Poetry or project tooling is required or configured
• CI-compatible workflows function without translation

---

Alignment With ADR

This feature explicitly implements AD-2026-02-09-06 by:

• enforcing a conservative, standards-based baseline
• avoiding tooling lock-in
• preserving developer autonomy without fragmenting shared workflows
• keeping CI and compliance paths intentionally boring

---

Versioning Impact

• MINOR version bump
• Adds new OS support without breaking existing paths
• No changes to Debian or macOS behavior

[NickLinney]

Adding NickLinneyDev ADR for context/reference artifact.

AD-2026-02-09-06 — Python Development Environment Standards

Status

Accepted

Date

2026-02-09

Context

The project requires a clear, defensible standard for Python development environments that:

• Aligns with officially supported Python governance and tooling
• Minimizes long-term maintenance and supply-chain risk
• Remains compatible with enterprise compliance, security review, and CI/CD requirements
• Allows reasonable developer autonomy without fragmenting shared workflows

The Python ecosystem continues to evolve rapidly, with new tooling (e.g., unified package managers and workflow tools) gaining popularity among individual developers. While some of these tools offer performance or ergonomic benefits, they also introduce additional governance, longevity, and lock-in considerations.

The project already maintains multiple Architecture Decision Records (ADRs) and favors conservative, standards-based decisions that prioritize stability, auditability, and replaceability over short-term developer convenience.

Decision

The project standardizes on the following Python development environment baseline:

Canonical (Project / CI / Departmental Standard)

• Python: Official Python 3 releases
• Package Installer: pip
• Environment Isolation: venv
• Packaging Standards: PEP 517 / PEP 518 compliant builds
• Dependency Representation:
  • requirements.txt and/or constraints files
  • No mandatory tool-specific lockfile formats

All project builds, tests, and release pipelines must succeed using only this canonical toolchain.

Developer Workstations

• Developers may use additional tools locally (e.g., pipx, alternative package managers, or workflow accelerators) at their discretion.
• Any locally used tooling must not introduce artifacts, lockfiles, or workflows that are required by the project or CI pipeline.
• Contributions must conform to the canonical standards when pushed to shared branches.

Explicit Non-Requirements

• No unified or monolithic Python tooling is required or mandated.
• No third-party package manager or workflow tool is considered authoritative for the project.
• Performance optimizations in local workflows are explicitly treated as optional and non-normative.

Rationale

This decision reflects the following principles:

• Standards over tools: Python’s PEP-defined packaging ecosystem is the stable contract; individual tools are interchangeable implementations.
• Replaceability: The canonical workflow must remain viable even if optional tools fall out of maintenance.
• Auditability: Compliance, security scanning, and SBOM generation are simplest when using widely recognized, officially supported tooling.
• UNIX-style separation of concerns: Discrete tools with narrow responsibilities are preferred over all-in-one abstractions for shared infrastructure.
• Risk containment: Allowing optional local tooling while enforcing a conservative CI boundary minimizes organizational blast radius.

This approach mirrors common enterprise practice: developers may optimize locally, but shared pipelines remain intentionally boring.

Consequences

Positive

• Clear, enforceable baseline for CI and compliance
• Minimal tooling lock-in
• Low friction for onboarding and cross-platform support
• Reduced long-term maintenance risk

Trade-offs

• Slower local workflows compared to some newer tools
• Developers may need to translate local setups into canonical forms
• Additional discipline required to keep CI as the source of truth

These trade-offs are considered acceptable given the project’s longevity, governance, and security goals.

Notes

This ADR does not prohibit future reevaluation. If an alternative tool becomes widely standardized, multi-vendor supported, and governance-mature, it may be reconsidered through a new ADR.

[NickLinney]

Update: Refined Implementation Plan for Windows Python Setup (ADR Alignment)

After reviewing the existing Windows setup scripts, we’ve identified that the current file at:

/env/Python/Windows/python_windows_new_setup.ps1

already largely conforms to the project’s accepted Python Development Environment Standards as defined in AD-2026-02-09-06.

The only substantive deviation is that the script installs Poetry as part of the default/global tool set.

Rather than introducing a new Windows setup script, we will proceed with a clean separation of concerns, aligning Windows with the same architectural model already used elsewhere in the repository.

Revised Direction

Baseline (Canonical / ADR-aligned):

• python_windows_new_setup.ps1 will be updated to:
  • Install official Python
  • Ensure pip and venv functionality
  • Avoid installing Poetry or any opinionated project tooling
  • Serve as the Windows-equivalent of the Debian “default Python” bootstrap

Optional / Developer Preferences:

• All Poetry-related logic (installation, configuration, preferences) will live exclusively in:
  · /env/Python/Windows/python_poetry_preferences.ps1
• This preserves developer autonomy while keeping the canonical baseline intentionally minimal and auditable.

Documentation Updates

The following documentation will be updated to reflect this separation:

• /env/Python/Windows/README.md
  • Update Quick Start guidance
  • Clearly distinguish baseline setup vs optional Poetry preferences
• /env/README.md
  • Correct any Windows references that imply Poetry is part of the default environment

Planning and Release Impact

• This work will be tracked under a new feature branch:
  · feature/env-4-python-windows-enforce-adr-defaults
• This change will be the core feature of:
  · release/0.4.0
• Version impact remains a MINOR bump, with no breaking changes to existing paths.

This approach brings Windows fully into alignment with the project’s ADRs, reinforces the canonical CI boundary, and avoids unnecessary duplication while preserving optional developer workflows.

[NickLinney]

Completed in commit 762f0b9.