Skip to content

Latest commit

 

History

History
337 lines (232 loc) · 7.09 KB

windows-development.md

File metadata and controls

337 lines (232 loc) · 7.09 KB

Windows Development Guide

This guide covers Windows-specific considerations when developing Auto Claude.

File Encoding

Problem

Windows Python defaults to the cp1252 (Windows-1252) code page instead of UTF-8. This causes encoding errors when reading/writing files with non-ASCII characters.

Common Error:

UnicodeDecodeError: 'charmap' codec can't decode byte 0x8d in position 1234

Solution

Always specify encoding="utf-8" for all text file operations.

See CONTRIBUTING.md - File Encoding for detailed examples and patterns.

Testing on Windows

To verify your code works on Windows:

  1. Test with non-ASCII content:

    # Include emoji, international chars in test data
test_data = {"message": "Test 🚀 with ñoño and 中文"}

  2. Run pre-commit hooks:

    pre-commit run check-file-encoding --all-files

  3. Run all tests:

    npm run test:backend

Common Pitfalls

Pitfall 1: JSON files

# Wrong - no encoding
with open("config.json") as f:
    data = json.load(f)

# Correct
with open("config.json", encoding="utf-8") as f:
    data = json.load(f)

Pitfall 2: Path methods

# Wrong
content = Path("README.md").read_text()

# Correct
content = Path("README.md").read_text(encoding="utf-8")

Pitfall 3: Subprocess output

# Wrong
result = subprocess.run(cmd, capture_output=True, text=True)

# Correct
result = subprocess.run(cmd, capture_output=True, encoding="utf-8")

Line Endings

Problem

Windows uses CRLF (\r\n) line endings while macOS/Linux use LF (\n). This can cause git diffs to show every line as changed.

Solution

  1. Configure git to handle line endings:

    git config --global core.autocrlf true

  2. The project's .gitattributes handles this automatically:

    * text=auto
*.py text eol=lf
*.md text eol=lf

  3. In code, normalize when processing:

    # Normalize line endings to LF (idiomatic approach)
content = "\n".join(content.splitlines())

Path Separators

Problem

Windows uses backslash \ for paths, while Unix uses /. This can break path operations.

Solution

  1. Always use Path from pathlib:

    from pathlib import Path

# Correct - works on all platforms
config_path = Path("config") / "settings.json"

# Wrong - Unix only
config_path = "config/settings.json"

  2. Use os.path.join() for strings:

    import os

# Correct
config_path = os.path.join("config", "settings.json")

  3. Never hardcode separators:

    # Wrong - Unix only
path = "apps/backend/core"

# Correct
path = os.path.join("apps", "backend", "core")
# Or better
path = Path("apps") / "backend" / "core"

Shell Commands

Problem

Windows doesn't have bash by default. Shell commands need to work across platforms.

Solution

  1. Use Python libraries instead of shell:

    # Instead of shell commands
import shutil
shutil.copy("source.txt", "dest.txt")  # Instead of cp

import os
os.remove("file.txt")  # Instead of rm

  2. Use shlex for cross-platform commands:

    import shlex
import subprocess

cmd = shlex.split("git rev-parse HEAD")
result = subprocess.run(cmd, capture_output=True, encoding="utf-8")

  3. Check platform when needed:

    import sys

if sys.platform == "win32":
    # Windows-specific code
    pass
else:
    # Unix code
    pass

Development Environment

Recommended Setup on Windows

  1. Use WSL2 (Windows Subsystem for Linux) - Recommended:

    • Most consistent with production Linux environment
    • Full bash support
    • Better performance for file I/O
    • Install from Microsoft Store or: wsl --install

  2. Or use Git Bash:

    • Comes with Git for Windows
    • Provides Unix-like shell
    • Lighter than WSL
    • Download from gitforwindows.org

  3. Or use PowerShell with Python:

    • Native Windows environment
    • Requires extra care with paths/encoding
    • Built into Windows

Editor Configuration

VS Code settings for Windows (settings.json):

{
  "files.encoding": "utf8",
  "files.eol": "\n",
  "python.analysis.typeCheckingMode": "basic",
  "editor.formatOnSave": true
}

Common Issues and Solutions

Issue: Permission errors when deleting files

Problem: Windows file locking is stricter than Unix.

Solution: Ensure files are properly closed using context managers:

# Use context managers
with open(path, encoding="utf-8") as f:
    data = f.read()
# File is closed here - safe to delete

Issue: Long path names

Problem: Windows has a 260-character path limit (legacy).

Solution:

  1. Enable long paths in Windows 10+ (Group Policy or Registry)
  2. Or keep paths short
  3. Or use WSL2

Issue: Case-insensitive filesystem

Problem: Windows filesystem is case-insensitive (File.txt == file.txt).

Solution: Be consistent with casing in filenames and imports:

# Consistent casing
from apps.backend.core import Client  # File: client.py

# Avoid mixing cases
from apps.backend.core import client  # Could work on Windows but fail on Linux

Testing Windows Compatibility

Before Submitting a PR

  1. Run pre-commit hooks:

    pre-commit run --all-files

  2. Run all tests:

    npm run test:backend
npm test  # frontend tests

  3. Test with special characters:

    # Add test data with emoji, international chars
test_content = "Test 🚀 ñoño 中文 العربية"

Windows-Specific Test Cases

Add tests for Windows compatibility when relevant:

import sys
import pytest

@pytest.mark.skipif(sys.platform != "win32", reason="Windows only")
def test_windows_encoding():
    """Test Windows encoding with special characters."""
    content = "Test 🚀 ñoño 中文"
    Path("test.txt").write_text(content, encoding="utf-8")
    loaded = Path("test.txt").read_text(encoding="utf-8")
    assert loaded == content

Getting Help

If you encounter Windows-specific issues:

  1. Check this guide and CONTRIBUTING.md
  2. Search existing issues
  3. Ask in discussions
  4. Create an issue with [Windows] tag

Resources

Related

  • CONTRIBUTING.md - General contribution guidelines
  • PR #782 - Comprehensive UTF-8 encoding fix
  • PR #795 - Pre-commit hooks for encoding enforcement