208 lines
6.1 KiB
Markdown
208 lines
6.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
pip install -r scripts/track_progress/requirements.txt
|
|
```
|
|
|
|
For development or building the executable, install all dependencies:
|
|
|
|
```bash
|
|
pip install -r scripts/track_progress/requirements.txt[all]
|
|
```
|
|
|
|
### Quick Install
|
|
|
|
Run the setup script to install the tracker to your project:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
python scripts/track_progress/track_progress.py --verbose
|
|
```
|