AdvChkSys/scripts/track_progress

Progress Tracker

A comprehensive tool for tracking project progress, feature status, and generating documentation from Git history.

Overview

The Progress Tracker analyzes your Git repository and codebase to automatically generate:

• Feature tracking documentation
• Project status reports
• Changelog based on commit messages
• Code statistics and metrics

Installation

Prerequisites

• Python 3.8 or higher
• Git

Dependencies

Install the required dependencies:

pip install -r scripts/track_progress/requirements.txt

For development or building the executable, install all dependencies:

pip install -r scripts/track_progress/requirements.txt[all]

Quick Install

Run the setup script to install the tracker to your project:

python scripts/track_progress/scripts/setup_install.py --project "Your Project Name" --dest path/to/destination

Options:

• --project name: Set your project name
• --dest folder: Set destination directory (default: "scripts")
• --verbose or -v: Enable verbose output
• --force or -f: Force overwrite existing files

Manual Installation

1. Copy the track_progress directory to your project
2. Create a docs/status directory in your project root
3. Create a docs/features.md file if it doesn't exist
4. Create a CHANGELOG.md file in your project root

Usage

Basic Usage

Run the tracker with default settings:

# Using the Python script
python scripts/track_progress/track_progress.py

# Using the executable (if built)
scripts/track_progress/track_progress

Command-Line Options

The tracker supports the following command-line options:

--config PATH       Path to configuration file (default: scripts/track_progress/progress_config.json)
--project NAME      Project name (overrides config)
--output-dir DIR    Output directory for status document (overrides config)
--repo PATH         Repository path to analyze (default: current directory)
--verbose, -v       Enable verbose output

Examples:

# Specify a custom configuration file
python scripts/track_progress/track_progress.py --config path/to/config.json

# Override project name
python scripts/track_progress/track_progress.py --project "My Project"

# Specify output directory
python scripts/track_progress/track_progress.py --output-dir docs/my-status

# Analyze a different repository
python scripts/track_progress/track_progress.py --repo path/to/repo

# Enable verbose output
python scripts/track_progress/track_progress.py --verbose

Commit Message Tags

The tracker recognizes special tags in commit messages to update feature status and documentation:

Tag	Description	Example
[status:key]	Update status of a component	[status:database]
[feature:key]	Mark a feature as completed	[feature:login]
[new-feature:key:description]	Add a new feature	[new-feature:search:Implement search functionality]
[changelog:message]	Add an entry to the changelog	[changelog:Added dark mode]
[fix:description]	Document a bug fix	[fix:Fixed login issue]
[issue:id]	Reference an issue	[issue:42]
[breaking]	Mark a breaking change	[breaking]
[roadmap:milestone:item]	Add an item to the roadmap	[roadmap:v2:Add OAuth support]
[milestone:key]	Reference a milestone	[milestone:v1.0]
[priority:level]	Set priority level	[priority:high]
[owner:name]	Assign an owner	[owner:John]
[tag:name]	Add a custom tag	[tag:security]

Example commit message:

Implement search functionality [feature:search] [changelog:Added search with filtering]

Configuration

The tracker uses a JSON configuration file (progress_config.json) with the following settings:

{
    "project_name": "Your Project",
    "output_dir": "docs/status",
    "status_doc": "status.md",
    "features_file": "docs/features.md",
    "changelog_file": "CHANGELOG.md",
    "git_log_limit": 100,
    "untagged_commit_limit": 50,
    "top_files_limit": 20,
    "exclude_dirs": ["node_modules", "venv", ".git"],
    "source_extensions": [".py", ".cs", ".js"],
    "templates": {
        "status": "status_template.md",
        "features": "feature_template.md",
        "changelog": "changelog_template.md"
    }
}

Output Files

The tracker generates the following files:

• docs/features.md: Feature tracking document
• docs/status/status.md: Project status document (or path specified in config)
• CHANGELOG.md: Project changelog

Components

The tracker consists of the following components:

• track_progress.py: Main script that orchestrates the tracking process
• config.py: Configuration management
• git_analyzer.py: Git history analysis
• code_stats.py: Code statistics and metrics
• feature_markdown.py: Feature tracking utilities
• template_engine.py: Template rendering engine
• changelog_generator.py: Changelog generation
• roadmap_generator.py: Roadmap generation

Building an Executable

You can build a standalone executable using Nuitka:

python scripts/track_progress/scripts/build_with_nuitka.py

This creates an executable in the scripts/track_progress/dist directory.

Customizing Templates

The tracker uses Markdown templates to generate documentation. You can customize these templates in the scripts/track_progress/templates directory:

• status_template.md: Template for the status document
• feature_template.md: Template for the feature tracking document
• changelog_template.md: Template for the changelog

The templates use a simple syntax:

• {{ variable }}: Insert a variable
• {% if condition %}...{% endif %}: Conditional block
• {% for item in items %}...{% endfor %}: Loop over items

Troubleshooting

Common Issues

1. Missing Git Repository: Ensure you're running the tracker in a Git repository.
2. No Features Found: Create a basic docs/features.md file with at least one feature.
3. Template Not Found: Check that templates exist in the templates directory.

Debug Mode

Run with --verbose to see detailed output:

python scripts/track_progress/track_progress.py --verbose