Skip to content

QUICKSTART.md

Latest commit

 

History

History
364 lines (276 loc) · 8.21 KB

QUICKSTART.md

File metadata and controls

364 lines (276 loc) · 8.21 KB

Quick Start Guide

Create Pull Request Action (Python Port)

This guide will help you get started with the Python port of create-pull-request action in 5 minutes.

1. Verify Installation

cd /Users/dikshant/Documents/personal/create-pull-request-python

# Check project structure
ls -la

# Verify Python files
python3 -m py_compile src/create_pull_request/*.py
echo "✓ All modules compiled successfully"

2. Install Dependencies

# Install runtime dependencies
pip3 install -r requirements.txt

# Install development dependencies (for testing)
pip3 install pytest pytest-cov pytest-mock ruff mypy

3. Run Tests

Unit Tests

# Run all unit tests
PYTHONPATH=src pytest tests/unit/ -v

# Run with coverage
PYTHONPATH=src pytest tests/unit/ -v --cov=src/create_pull_request --cov-report=term-missing

Integration Tests

# Run integration tests (requires git)
PYTHONPATH=src pytest tests/integration/ -v

All Tests

# Run complete test suite
PYTHONPATH=src pytest tests/ -v --cov=src/create_pull_request --cov-report=html

# View coverage report
open htmlcov/index.html

4. Build Docker Image

# Build the Docker image
docker build -t create-pull-request-python:v1.0.0 .

# Check image size
docker images | grep create-pull-request-python

# Test the image (will show help since no git repo)
docker run --rm create-pull-request-python:v1.0.0 || true

5. Local Testing

Option A: Test with Python Directly

# Create a test git repository
mkdir -p /tmp/test-repo
cd /tmp/test-repo
git init
git config user.name "Test User"
git config user.email "test@example.com"
echo "# Test Repo" > README.md
git add README.md
git commit -m "Initial commit"

# Make some changes
echo "Updated content" > test.txt

# Set up environment variables
export INPUT_TOKEN="test-token"
export GITHUB_REPOSITORY="test-owner/test-repo"
export INPUT_BRANCH="test-branch"
export INPUT_COMMIT_MESSAGE="Test commit"
export INPUT_TITLE="Test PR"

# Run the action (will fail at GitHub API step without valid token, but validates local git operations)
cd /Users/dikshant/Documents/personal/create-pull-request-python
PYTHONPATH=src python3 -m create_pull_request

Option B: Test with Docker

# From a git repository with changes
docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  -e INPUT_TOKEN=$GITHUB_TOKEN \
  -e GITHUB_REPOSITORY=owner/repo \
  -e INPUT_BRANCH=test-branch \
  -e INPUT_TITLE="Test PR" \
  -e INPUT_COMMIT_MESSAGE="Test changes" \
  create-pull-request-python:v1.0.0

6. Initialize Git Repository

cd /Users/dikshant/Documents/personal/create-pull-request-python

# Initialize git (if not already done)
git init

# Add all files
git add .

# Create initial commit
git commit -m "feat: Python port of create-pull-request action

- Complete feature parity with TypeScript version
- 2,770 lines of source code
- 643 lines of test code
- Comprehensive documentation
- CI/CD workflows
- Docker packaging"

7. Publish to GitHub

Create Repository on GitHub

# Using GitHub CLI (recommended)
gh repo create create-pull-request-python --public --description "Python port of create-pull-request GitHub Action"

# Add remote
git remote add origin https://github.com/YOUR-USERNAME/create-pull-request-python.git

# Push code
git push -u origin main

Or via Web Interface

  1. Go to https://github.com/new
  2. Create repository: create-pull-request-python
  3. Add remote and push: 
    git remote add origin https://github.com/YOUR-USERNAME/create-pull-request-python.git
git push -u origin main

8. Create First Release

# Tag the release
git tag -a v1.0.0 -m "Release v1.0.0 - Initial Python port"

# Push the tag
git push origin v1.0.0

# This will trigger the release workflow which will:
# - Build Docker image
# - Push to GitHub Container Registry
# - Create GitHub Release

9. Use in GitHub Actions

In Your Repository

Create .github/workflows/test-pr-action.yml:

name: Test Create PR Action

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  test-action:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Make some changes
        run: |
          echo "Updated at $(date)" > update.txt
          echo "This is a test change" >> README.md

      - name: Create Pull Request
        uses: YOUR-USERNAME/create-pull-request-python@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: "test: Automated update"
          branch: automated-update
          title: "Automated Update Test"
          body: |
            This PR was created automatically to test the Python port of create-pull-request action.

            ## Changes
            - Updated update.txt with timestamp
            - Modified README.md

          labels: |
            automated
            test
          draft: true

10. Verify Everything Works

Run All Checks

cd /Users/dikshant/Documents/personal/create-pull-request-python

# 1. Syntax check
python3 -m py_compile src/create_pull_request/*.py
echo "✓ Syntax valid"

# 2. Import check
python3 -c "import sys; sys.path.insert(0, 'src'); import create_pull_request; print('✓ Package imports successfully')"

# 3. Version check
python3 -c "import sys; sys.path.insert(0, 'src'); from create_pull_request import __version__; print(f'Version: {__version__}')"

# 4. Run tests
PYTHONPATH=src pytest tests/unit/ -v --tb=short
echo "✓ Tests pass"

# 5. Build Docker
docker build -t create-pull-request-python:test . > /dev/null 2>&1
echo "✓ Docker builds"

# 6. Lint check (optional)
pip3 install ruff 2>/dev/null
ruff check src/ || echo "⚠ Linting found issues (non-critical)"

Troubleshooting

Common Issues

Issue: ModuleNotFoundError: No module named 'github'

# Solution: Install PyGithub
pip3 install PyGithub

Issue: Tests fail with git errors

# Solution: Configure git globally
git config --global user.name "Test User"
git config --global user.email "test@example.com"

Issue: Docker build fails

# Solution: Check Docker is running
docker info

# Rebuild with verbose output
docker build --progress=plain -t create-pull-request-python:test .

Issue: Import errors in tests

# Solution: Set PYTHONPATH
export PYTHONPATH=src
pytest tests/ -v

Next Steps

  1. ✅ Read the README.md for complete documentation
  2. ✅ Check IMPLEMENTATION_SUMMARY.md for architecture details
  3. ✅ Review action.yml for all input/output parameters
  4. ✅ Browse tests/ for usage examples
  5. ✅ See .github/workflows/ for CI/CD examples

Example Workflows

Automated Dependency Updates

name: Update Dependencies
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update dependencies
        run: |
          pip install --upgrade pip
          pip list --outdated --format=json | jq -r '.[].name' | xargs pip install -U
          pip freeze > requirements.txt
      - uses: YOUR-USERNAME/create-pull-request-python@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          branch: deps-update
          title: "chore: Update dependencies"
          labels: dependencies

Automated Code Formatting

name: Format Code
on:
  pull_request:

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}
      - name: Format with black
        run: |
          pip install black
          black .
      - uses: YOUR-USERNAME/create-pull-request-python@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          branch: auto-format-${{ github.head_ref }}
          title: "style: Auto-format ${{ github.head_ref }}"
          labels: formatting

Support

  • 📖 Documentation: README.md
  • 🐛 Issues: GitHub Issues
  • 💬 Discussions: GitHub Discussions
  • 📧 Contact: Create an issue for support

You're all set! 🎉

The Python port of create-pull-request action is ready to use in your workflows.