Skip to content

Latest commit

 

History

History
229 lines (176 loc) · 6.16 KB

CONTRIBUTING.md

File metadata and controls

229 lines (176 loc) · 6.16 KB
Raw

Contributing to Pull

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Development Environment

Prerequisites

  • Deno 2.1.1 or later
  • MongoDB 8.0
  • Redis 7.4

Development Containers

We provide two development environments:

  1. Base Environment:
devcontainer open .devcontainer/pull-base
  1. Full Environment (includes monitoring tools which supports amd64 only):
devcontainer open .devcontainer/pull-full

The full environment includes additional tools:

  • Mongo Express (port 8081)
  • Redis Commander (port 8082)
  • Bull Board (port 8083)

Getting Started

  1. Fork and clone the repository
  2. Make sure you have Deno installed
  3. Install development hooks: 
    deno task install-hooks
  4. Set up your GitHub App. Follow the Probot documentation for detailed instructions on creating a GitHub App.
  5. Set up your environment variables by copying the .env.example file to .env and filling in the required values: 
    cp .env.example .env
  6. Start the development server: 
    deno task dev
    Start the development worker: 
    deno task worker

Available Scripts

  • deno task dev: Start the app in development mode
  • deno task dev:skip-full-sync: Start without initial full sync
  • deno task worker: Start the background worker
  • deno task test: Run tests
  • deno task check: Run linter and formatter checks
  • deno task full-sync: Run full repository sync
  • deno task manual-process <owner>/<repo>: Process specific repository

Application Architecture

Core Components

1. Web Server (src/index.ts)

The main Express.js application that:

  • Handles GitHub webhooks
  • Serves API endpoints
  • Initializes the scheduler

2. Background Worker (src/worker.ts)

Processes repository sync jobs using BullMQ:

  • Handles job concurrency
  • Manages retries and failures
  • Processes jobs based on priority

3. Scheduler (@wei/probot-scheduler)

Manages periodic repository checks:

  • Schedules jobs using cron expressions
  • Maintains job queues in Redis
  • Handles job priorities and scheduling

4. Database Layer

  • MongoDB: Stores repository and installation data
  • Redis: Manages job queues and caching
  • Connections: Managed through src/configs/database.ts and src/configs/redis.ts

5. Pull Processor (src/processor/pull.ts)

The Pull processor is the core component that handles repository synchronization. Here's a detailed breakdown of its functionality:

graph TD
    A[Routine Check] --> B{Has Diff?}
    B -->|Yes| C{Existing PR?}
    B -->|No| D[Skip]
    C -->|Yes| E[Check Auto Merge]
    C -->|No| F[Create PR]
    F --> E
    E --> G{Mergeable?}
    G -->|Yes| H[Process Merge]
    G -->|No| I[Handle Conflict]
Loading
Main Components

  1. Routine Check (routineCheck):

    • Iterates through configured rules in pull.yml
    • For each rule:
      • Normalizes base and upstream branch names
      • Checks for differences between branches
      • Creates or updates pull requests as needed

  2. Difference Detection (hasDiff):

    • Compares commits between base and upstream branches
    • Handles special cases:
      • Large diffs that timeout
      • Missing branches
      • No common ancestor
    • Returns true if changes are detected

  3. Pull Request Management:

    • Updates (getOpenPR):
      • Finds existing PRs created by the bot
      • Validates PR matches current sync rule
    • Creation (createPR):
      • Creates new pull request with standardized title
      • Assigns reviewers and labels
      • Updates PR body with tracking information

  4. Merge Process (checkAutoMerge, processMerge):

    • Supports multiple merge methods:
      • none: No automatic merging
      • merge: Standard merge commit
      • squash: Squash and merge
      • rebase: Rebase and merge
      • hardreset: Force push to base branch
    • Handles merge conflicts:
      • Adds conflict label
      • Assigns conflict reviewers
      • Updates PR status
Error Handling

The processor implements robust error handling:

  • Retries for mergeable status checks
  • Graceful handling of GitHub API limitations
  • Detailed logging for debugging
  • Conflict resolution workflows
Best Practices

When modifying the Pull processor:

  1. Maintain idempotency in operations
  2. Implement proper error handling
  3. Add detailed logging for debugging
  4. Consider edge cases

Submitting a Pull Request

  1. Create a new branch: git checkout -b my-branch-name
  2. Make your changes
  3. Make sure the tests pass: 
    deno test
  4. Format your code: 
    deno fmt
  5. Run the linter: 
    deno lint
  6. Push to your fork and submit a pull request
  7. Pat yourself on the back and wait for your pull request to be reviewed and merged

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Follow the style guide enforced by Deno's built-in formatter. You can format your code by running deno fmt
  • Write and update tests
  • Keep your changes as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests
  • Write a good commit message

Work in Progress pull requests are also welcome to get feedback early on, or if there is something blocked you.

Resources

License

By contributing, you agree that your contributions will be licensed under its MIT License.