跳转至

Development Infrastructure Setup - Summary

Date: 2024-11-01\ Author: SAGE Team\ Summary: 开发基础设施配置指南

Date: 2025-10-02\ Commits:

  • 510ae5e7 - docs: reorganize and cleanup dev-notes directory (#880)
  • 49586b5c - feat: add development infrastructure and documentation

🎯 What Was Added

1. CHANGELOG.md

  • Follows Keep a Changelog format
  • Tracks all notable changes to the project
  • Includes guidelines for maintaining the changelog
  • Categories: Added, Changed, Deprecated, Removed, Fixed, Security
  • Adheres to Semantic Versioning

Location: /CHANGELOG.md

2. Pre-commit Configuration

  • File: tools/pre-commit-config.yaml
  • Purpose: Automated code quality checks before commits

Hooks included:

  • General checks: trailing whitespace, end-of-file, YAML/JSON validation
  • Python formatting: black (line-length=100), isort (black profile)
  • Python linting: ruff (fast linter), mypy (type checking)
  • Shell checking: shellcheck for bash scripts
  • YAML/Markdown: formatting and validation
  • Security: detect-secrets to prevent credential leaks

Installation:

pre-commit install

Usage:

# Run manually
pre-commit run --all-files

# Update hooks
pre-commit autoupdate

3. Developer Helper Script

  • File: scripts/dev.sh
  • Purpose: Common development commands in one place
  • Executable: Yes (chmod +x)

Available commands:

./scripts/dev.sh setup          # Initial dev setup
./scripts/dev.sh install        # Install in dev mode
./scripts/dev.sh test           # Run all tests
./scripts/dev.sh test-unit      # Unit tests only
./scripts/dev.sh test-integration  # Integration tests only
./scripts/dev.sh lint           # Run linters
./scripts/dev.sh format         # Format code
./scripts/dev.sh check          # Check format without changes
./scripts/dev.sh pre-commit     # Run pre-commit hooks
./scripts/dev.sh clean          # Clean artifacts
./scripts/dev.sh docs           # Build documentation
./scripts/dev.sh serve-docs     # Serve docs locally
./scripts/dev.sh validate       # Run all checks
./scripts/dev.sh help           # Show help

Features:

  • Color-coded output
  • Error handling
  • Comprehensive validation suite
  • Helpful error messages

4. Developer Guide

  • File: DEVELOPER.md
  • Purpose: Comprehensive guide for contributors

Sections:

  • Development setup instructions
  • Development workflow with dev.sh
  • Code quality standards (black, isort, ruff, mypy)
  • Testing guidelines and best practices
  • Documentation writing guide
  • Release process
  • Contributing guidelines
  • Pull request process

5. Architecture Diagram

  • File: docs/images/architecture.svg
  • Purpose: Visual representation of SAGE architecture
  • Format: SVG (scalable vector graphics)

Layers shown:

  1. User Layer (Applications)
  2. API Layer (LocalEnvironment, RemoteEnvironment)
  3. Core Layer (Dispatcher, Job Manager, Services, Runtime)
  4. Libraries Layer (RAG, Agents, Memory, Middleware, Tools)
  5. Infrastructure Layer (Compute, Storage, Models, Monitoring)

Referenced in:

  • README.md (Architecture Excellence section)
  • DEVELOPER.md (Useful Resources)

6. Secrets Baseline

  • File: tools/secrets.baseline
  • Purpose: Baseline for detect-secrets hook
  • Content: Empty JSON object {}
  • Usage: Prevents false positives in secret detection

7. Updated Documentation

README.md

  • Added "System Architecture" section with diagram
  • Reorganized architecture content
  • Better visual structure

CONTRIBUTING.md

  • Added "Developer Resources" section at the top
  • Links to all new documentation
  • Quick start commands with dev.sh

📊 Statistics

Files Added: 6

  • tools/pre-commit-config.yaml
  • tools/secrets.baseline
  • CHANGELOG.md
  • DEVELOPER.md
  • docs/images/architecture.svg
  • scripts/dev.sh

Files Modified: 2

  • CONTRIBUTING.md
  • README.md

Files Moved: 1

  • dev.sh → scripts/dev.sh

Total Lines Added: ~1,149 lines

🚀 Quick Start for Developers

First Time Setup

# Clone and setup
git clone https://github.com/intellistream/SAGE.git
cd SAGE

# Run automated setup
./scripts/dev.sh setup

# Verify everything works
./scripts/dev.sh validate

Daily Development Workflow

# Before making changes
git checkout -b feature/my-feature

# Make your changes...

# Format and check
./scripts/dev.sh format
./scripts/dev.sh lint

# Run tests
./scripts/dev.sh test

# Run all validation
./scripts/dev.sh validate

# Commit (pre-commit hooks run automatically)
git add .
git commit -m "feat: my new feature"

Pre-commit Hooks

Pre-commit hooks run automatically on git commit. They will:

  • Format your code (black, isort)
  • Check for linting issues (ruff, mypy)
  • Validate shell scripts (shellcheck)
  • Check for secrets (detect-secrets)
  • Fix trailing whitespace and line endings

If hooks fail, fix the issues and commit again.

🎨 Code Quality Standards

Python Code Style

  • Line length: 100 characters
  • Formatter: black
  • Import sorting: isort (black profile)
  • Linter: ruff
  • Type checking: mypy

Shell Scripts

  • Checker: shellcheck
  • Style: Follow Google Shell Style Guide
  • Shebang: Use #!/usr/bin/env bash

Commit Messages

Follow Conventional Commits:

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation only
  • style: Formatting, no code change
  • refactor: Code restructuring
  • test: Adding/updating tests
  • chore: Build process, tooling

📖 Documentation Structure

SAGE/
├── CHANGELOG.md           # Project changelog
├── CONTRIBUTING.md        # Contribution guidelines
├── DEVELOPER.md          # Developer guide
├── README.md             # Main documentation
├── tools/
│   ├── pre-commit-config.yaml  # Pre-commit hooks
│   └── secrets.baseline        # Secrets detection baseline
├── docs/
│   ├── images/
│   │   └── architecture.svg  # Architecture diagram
│   └── dev-notes/        # Development notes
│       ├── TEMPLATE.md   # Dev note template
│       ├── QUICK_START.md  # Quick start guide
│       └── README.md     # Dev notes overview
└── scripts/
    └── dev.sh            # Developer helper script

🔧 Troubleshooting

Pre-commit Hooks Not Running

# Reinstall hooks
pre-commit uninstall
pre-commit install

Format Check Fails

# Auto-fix formatting
./scripts/dev.sh format

Tests Fail

# Run with verbose output
pytest tests/ -vv

# Run specific test
pytest tests/test_specific.py::test_function -v

Dev Script Permission Denied

# Make executable
chmod +x scripts/dev.sh

🎉 Benefits

For Developers

  • ✅ Consistent code style across the project
  • ✅ Automated quality checks before commit
  • ✅ Easy-to-use development commands
  • ✅ Clear documentation and guidelines
  • ✅ Visual architecture reference

For the Project

  • ✅ Higher code quality
  • ✅ Fewer bugs and issues
  • ✅ Easier onboarding for new contributors
  • ✅ Better maintainability
  • ✅ Professional development workflow

For Maintainers

  • ✅ Standardized changelog format
  • ✅ Automated code review checks
  • ✅ Clear release process
  • ✅ Better code organization
  • ✅ Reduced review time

✅ Checklist

Development infrastructure is now complete:

  • [x] CHANGELOG.md added
  • [x] Pre-commit config created
  • [x] Developer helper script created
  • [x] Developer guide written
  • [x] Architecture diagram created
  • [x] README updated with diagram
  • [x] CONTRIBUTING.md updated
  • [x] All files committed and pushed
  • [x] Documentation verified

Status: ✅ Complete\ Next Steps: Contributors can now use the new development workflow!