Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
184 lines (138 loc) · 4.37 KB

DEVELOPMENT.md

File metadata and controls

184 lines (138 loc) · 4.37 KB
Raw

Development Setup Guide

This guide will help you set up a development environment for the github-backup-app project using modern Python tooling.

Prerequisites

  • Python 3.14+ (tested with Python 3.14.6)
  • Git
  • uv (fast Python package manager)

Quick Setup

1. Clone the Repository

git clone https://github.com/schlomo/github-backup-app.git
cd github-backup-app

2. Install uv (if not already installed)

# On macOS with Homebrew (recommended)
brew install uv

# Or using the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

3. Set up Development Environment

Option A: Using the setup script (recommended):

./dev-setup.sh

Option B: Manual setup:

# Install all dependencies (runtime + dev)
uv sync --dev

# Activate the virtual environment
source .venv/bin/activate

# Verify installation
python -c "import github_backup; print('Import successful')"

Option C: Using uv directly:

uv sync --dev

4. Verify Installation

First, activate the virtual environment:

source .venv/bin/activate

Then test the installation:

# Test the CLI
github-backup --help

# Test linting
flake8 github_backup/

# Test code formatting
black --check github_backup/

# Test import
python -c "import github_backup; print('Import successful')"

Development Tools

Code Quality Tools

  • flake8: Linting and style checking
  • black: Code formatting
  • autopep8: Automatic PEP 8 formatting

Testing

Currently, this project has no unit tests. To run linting:

# Activate the virtual environment first
source .venv/bin/activate

# Then run linting
flake8 github_backup/

Code Formatting

To format code with black:

# Activate the virtual environment first
source .venv/bin/activate

# Then format code
black github_backup/

To check formatting without making changes:

black --check github_backup/

Project Structure

github-backup-app/
├── github_backup/                   # Main package
│   ├── __init__.py                  # Package initialization
│   ├── __main__.py                  # Backup tool CLI entry point
│   ├── github_backup.py             # Main application logic
│   └── create_github_app.py         # Script to automate creation of a GitHub App
├── .github/
│   └── workflows/                   # GitHub Actions CI/CD
│       └── ci-cd.yml                # Test, build, Docker and PyPI release
├── Dockerfile                       # Container image definition
├── pyproject.toml                   # Modern Python packaging configuration
├── uv.lock                          # Dependency lock file
├── dev-setup.sh                     # Development setup script
├── .flake8                          # Flake8 configuration
└── README.md                        # Project documentation

Running the Application

Basic Usage

First, activate the virtual environment:

source .venv/bin/activate

Then use the application:

# Show help
github-backup --help

# Backup a user's public repositories (requires GitHub App authentication)
github-backup username --app-id YOUR_APP_ID --private-key YOUR_PRIVATE_KEY --output-directory ./backup

Development Testing

# Activate the virtual environment first
source .venv/bin/activate

# Run directly from source as a module
python -m github_backup --help

# Use the installed command
github-backup --help

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Set up development environment: ./dev-setup.sh
  4. Activate the virtual environment: source .venv/bin/activate
  5. Make your changes
  6. Run linting: flake8 github_backup/
  7. Format code: black github_backup/
  8. Test your changes: python -c "import github_backup; print('Import successful')"
  9. Submit a pull request

The CI/CD pipeline will automatically run tests, linting, and formatting checks on your pull request.

Cutting a release

# 1. Bump __version__ in github_backup/__init__.py
# 2. Commit, merge to main (updates :latest Docker image)
# 3. Tag for PyPI + semver Docker tags:
git tag v0.2.0
git push origin v0.2.0

Ensure PYPI_API_TOKEN is configured under repository Secrets before tagging, or the PyPI job will fail (Docker will still publish).