1- ## Contributing
1+ # Contributing to Pull
22
33Hi there! We're thrilled that you'd like to contribute to this project. Your
44help is essential for keeping it great.
55
66Please note that this project is released with a
7- [ Contributor Code of Conduct] [ code-of-conduct ] . By participating in this project
8- you agree to abide by its terms.
7+ [ Contributor Code of Conduct] ( CODE_OF_CONDUCT.md ) . By participating in this
8+ project you agree to abide by its terms.
99
10- ## Submitting a pull request
10+ ## Development Environment
11+
12+ ### Prerequisites
13+
14+ - [ Deno] ( https://deno.land/#installation ) 2.0.6 or later
15+ - MongoDB 8.0
16+ - Redis 7.4
17+
18+ ### Development Containers
19+
20+ We provide two development environments:
21+
22+ 1 . Base Environment:
23+
24+ ``` bash
25+ devcontainer open .devcontainer/pull-base
26+ ```
27+
28+ 2 . Full Environment (includes monitoring tools which supports amd64 only):
29+
30+ ``` bash
31+ devcontainer open .devcontainer/pull-full
32+ ```
33+
34+ The full environment includes additional tools:
35+
36+ - Mongo Express (port 8081)
37+ - Redis Commander (port 8082)
38+ - Bull Board (port 8083)
39+
40+ ## Getting Started
41+
42+ 1 . Fork and clone the repository
43+ 2 . Make sure you have [ Deno] ( https://deno.land/#installation ) installed
44+ 3 . Install development hooks:
45+ ``` bash
46+ deno task install-hooks
47+ ```
48+ 4 . Set up your GitHub App. Follow the
49+ [ Probot documentation] ( https://probot.github.io/docs/development/ ) for
50+ detailed instructions on creating a GitHub App.
51+ 5 . Set up your environment variables by copying the ` .env.example ` file to
52+ ` .env ` and filling in the required values:
53+ ``` sh
54+ cp .env.example .env
55+ ```
56+ 6 . Start the development server:
57+ ``` bash
58+ deno task dev
59+ ```
60+ Start the development worker:
61+ ``` bash
62+ deno task worker
63+ ```
64+
65+ ## Available Scripts
66+
67+ - ` deno task dev ` : Start the app in development mode
68+ - ` deno task dev:skip-full-sync ` : Start without initial full sync
69+ - ` deno task worker ` : Start the background worker
70+ - ` deno task test ` : Run tests
71+ - ` deno task check ` : Run linter and formatter checks
72+ - ` deno task full-sync ` : Run full repository sync
73+ - ` deno task manual-process <owner>/<repo> ` : Process specific repository
74+
75+ ## Application Architecture
76+
77+ ### Core Components
78+
79+ #### 1. Web Server (` src/index.ts ` )
80+
81+ The main Express.js application that:
82+
83+ - Handles GitHub webhooks
84+ - Serves API endpoints
85+ - Initializes the scheduler
86+
87+ #### 2. Background Worker (` src/worker.ts ` )
88+
89+ Processes repository sync jobs using BullMQ:
90+
91+ - Handles job concurrency
92+ - Manages retries and failures
93+ - Processes jobs based on priority
94+
95+ #### 3. Scheduler ([ ` @wei/probot-scheduler ` ] ( https://jsr.io/@wei/probot-scheduler ) )
96+
97+ Manages periodic repository checks:
98+
99+ - Schedules jobs using cron expressions
100+ - Maintains job queues in Redis
101+ - Handles job priorities and scheduling
102+
103+ #### 4. Database Layer
104+
105+ - ** MongoDB** : Stores repository and installation data
106+ - ** Redis** : Manages job queues and caching
107+ - ** Connections** : Managed through ` src/configs/database.ts ` and
108+ ` src/configs/redis.ts `
109+
110+ #### 5. Pull Processor (` src/processor/pull.ts ` )
111+
112+ The Pull processor is the core component that handles repository
113+ synchronization. Here's a detailed breakdown of its functionality:
114+
115+ ``` mermaid
116+ graph TD
117+ A[Routine Check] --> B{Has Diff?}
118+ B -->|Yes| C{Existing PR?}
119+ B -->|No| D[Skip]
120+ C -->|Yes| E[Check Auto Merge]
121+ C -->|No| F[Create PR]
122+ F --> E
123+ E --> G{Mergeable?}
124+ G -->|Yes| H[Process Merge]
125+ G -->|No| I[Handle Conflict]
126+ ```
127+
128+ ##### Main Components
129+
130+ 1 . ** Routine Check (` routineCheck ` ):**
131+ - Iterates through configured rules in ` pull.yml `
132+ - For each rule:
133+ - Normalizes base and upstream branch names
134+ - Checks for differences between branches
135+ - Creates or updates pull requests as needed
136+
137+ 2 . ** Difference Detection (` hasDiff ` ):**
138+ - Compares commits between base and upstream branches
139+ - Handles special cases:
140+ - Large diffs that timeout
141+ - Missing branches
142+ - No common ancestor
143+ - Returns true if changes are detected
144+
145+ 3 . ** Pull Request Management:**
146+ - ** Updates (` getOpenPR ` ):**
147+ - Finds existing PRs created by the bot
148+ - Validates PR matches current sync rule
149+ - ** Creation (` createPR ` ):**
150+ - Creates new pull request with standardized title
151+ - Assigns reviewers and labels
152+ - Updates PR body with tracking information
153+
154+ 4 . ** Merge Process (` checkAutoMerge ` , ` processMerge ` ):**
155+ - Supports multiple merge methods:
156+ - ` none ` : No automatic merging
157+ - ` merge ` : Standard merge commit
158+ - ` squash ` : Squash and merge
159+ - ` rebase ` : Rebase and merge
160+ - ` hardreset ` : Force push to base branch
161+ - Handles merge conflicts:
162+ - Adds conflict label
163+ - Assigns conflict reviewers
164+ - Updates PR status
165+
166+ ##### Error Handling
167+
168+ The processor implements robust error handling:
169+
170+ - Retries for mergeable status checks
171+ - Graceful handling of GitHub API limitations
172+ - Detailed logging for debugging
173+ - Conflict resolution workflows
174+
175+ ##### Best Practices
176+
177+ When modifying the Pull processor:
178+
179+ 1 . Maintain idempotency in operations
180+ 2 . Implement proper error handling
181+ 3 . Add detailed logging for debugging
182+ 4 . Consider edge cases
183+
184+ ## Submitting a Pull Request
11185
12- 1 . [ Fork] [ fork ] and clone the repository
13- 1 . Make sure you have [ Deno installed] ( https://deno.land/#installation )
14- 1 . Make sure the tests pass on your machine: ` deno test `
151861 . Create a new branch: ` git checkout -b my-branch-name `
16- 1 . Make your change, add tests, and make sure the tests still pass
17- 1 . Make sure the code is formatted: ` deno fmt `
18- 1 . Make sure the linter passes on your machine: ` deno lint `
19- 1 . Push to your fork and [ submit a pull request] [ pr ]
20- 1 . Pat your self on the back and wait for your pull request to be reviewed and
21- merged.
187+ 2 . Make your changes
188+ 3 . Make sure the tests pass:
189+ ``` bash
190+ deno test
191+ ```
192+ 4 . Format your code:
193+ ``` bash
194+ deno fmt
195+ ```
196+ 5 . Run the linter:
197+ ``` bash
198+ deno lint
199+ ```
200+ 6 . Push to your fork and submit a pull request
201+ 7 . Pat yourself on the back and wait for your pull request to be reviewed and
202+ merged
22203
23204Here are a few things you can do that will increase the likelihood of your pull
24205request being accepted:
25206
26207- Follow the style guide enforced by Deno's built-in formatter. You can format
27208 your code by running ` deno fmt `
28- - Write and update tests.
29- - Keep your change as focused as possible. If there are multiple changes you
209+ - Write and update tests
210+ - Keep your changes as focused as possible. If there are multiple changes you
30211 would like to make that are not dependent upon each other, consider submitting
31- them as separate pull requests.
212+ them as separate pull requests
32213- Write a
33- [ good commit message] ( http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html ) .
214+ [ good commit message] ( http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html )
34215
35216Work in Progress pull requests are also welcome to get feedback early on, or if
36217there is something blocked you.
@@ -42,6 +223,7 @@ there is something blocked you.
42223- [ GitHub Help] ( https://help.github.com )
43224- [ Deno Manual] ( https://deno.land/manual )
44225
45- [ fork ] : ../../../fork
46- [ pr ] : ../../../compare
47- [ code-of-conduct ] : CODE_OF_CONDUCT.md
226+ ## License
227+
228+ By contributing, you agree that your contributions will be licensed under its
229+ MIT License.
0 commit comments