SIA/procedures/version_control/reasoning.md

Version Control

Version control is essential for SIA's self-improvement capabilities. It provides a way to track changes, revert to previous states when necessary, and maintain a coherent evolution of the codebase. This document outlines the git workflow designed specifically for SIA's unique development model, where the agent itself is the primary developer.

Core Principles

The git workflow for SIA is designed around several key principles:

• Simplicity: Since SIA is the sole developer, complex branching strategies designed for human teams are unnecessary
• Traceability: Every change should be traceable to its purpose and the reasoning behind it
• Stability: The master branch should always be in a working state
• Recoverability: It should always be possible to revert to a known good state
• Security: Git credentials must be handled securely to protect repository access

Branching Strategy

Branch Structure

SIA uses a simple branching strategy with two types of branches:

• master: The main branch containing stable, production-ready code
• feature/{timestamp}_{description}: Temporary branches for implementing specific improvements

This minimal approach is appropriate because:

• There is only one developer (SIA itself)
• Changes are typically focused on specific, well-defined improvements
• There's no need for parallel development streams
• Simplicity reduces the cognitive load on the agent

Branch Naming

Feature branches follow a consistent naming convention:

feature/{YYYYMMDD}_{brief_description}

For example:

feature/20250115_improve_context_management
feature/20250203_add_email_tool

This convention:

• Makes it easy to identify when a branch was created
• Provides a clear indication of the branch's purpose
• Creates a chronological ordering when listing branches
• Avoids potential naming conflicts

Commit Strategy

Commit Frequency

SIA should commit changes before running tests. This ensures that crashes of the core system can be traced back to a specific change.

Commit Messages

Commit messages should follow a structured format:

{type}: {concise description}

{detailed explanation of changes and reasoning}

{reference to any relevant issues or test results}

Where {type} is one of:

• core: for changes on the core system
• procedure: for changes on procedures
• test: for changes on tests
• tool: for changes on tools
• training: for changes on training data
• web: for changes on the web interface

This structure:

• Makes it easy to understand the purpose of each commit
• Provides context for future review
• Creates a useful and navigable history

Merge Strategy

The --no-ff flag creates a merge commit even for fast-forward merges, maintaining a clear record of the feature's development and completion.

Credential Management

Credential Storage

Git credentials are stored in the environment, not in the filesystem. This ensures that credentials are not exposed in the iteration log. Info about the repository and relevant environment variables is stored in /root/data/environment/sia_repo.md.