Pull request kwenye Git: ni nini na jinsi ya kuunda PR kwenye GitHub

Pull request (PR) ni pendekezo la kuunganisha mabadiliko kutoka tawi moja kwenda jingine, lililoandikwa kwenye jukwaa kama GitHub. Unatuma tawi kwenye seva, unafungua PR, timu inaona diff, inaacha maoni kwenye mistari, inaendesha ukaguzi wa kiotomatiki, na ndipo mtu anabonyeza kitufe cha kuunganisha. Kwenye GitLab utaratibu huo huo unaitwa merge request (MR). Kwa ufupi, pull request ni kituo cha udhibiti kati ya «nimeandika msimbo» na «msimbo umeingia kwenye main».

Git pull request ni nini na jina lake linatoka wapi

Jina lilitokana na historia. Mwandishi wa mabadiliko anamwomba mmiliki wa repository «kuvuta» (pull) tawi lake kwenye tawi lake mwenyewe, na ndiyo maana ni pull request. GitLab waliamua kulipa jina kwa matokeo yake — merge request, yaani ombi la kuunganisha. Bitbucket na Azure DevOps wanatumia neno «pull request». Kwa maana halisi ni kitu kimoja: tawi la chanzo, tawi lengwa, maelezo, majadiliano, ukaguzi na kitufe cha kuunganisha.

Ni muhimu kuelewa kwamba pull request si sehemu ya Git. Hakuna kitu kinachoitwa «PR» ndani ya Git; huwezi kuiunda kwa commit wala kuipata kwenye folda ya .git. Ni kitu cha jukwaa: GitHub inahifadhi maelezo, maoni na hali za ukaguzi kwenye seva yake, wakati Git inashughulikia matawi na commit tu zinazoingia kwenye PR.

Kwenye mazungumzo ya wasanidi, neno PR kwa kawaida linamaanisha pull request: «nitumie PR», «PR iko tayari kwa ukaguzi», «nimeunganisha PR». Kwa GitLab wanasema MR.

Pull request na git pull: tofauti yake

Kwa sababu ya maneno yanayofanana, watu wanachanganya mambo haya mara kwa mara. Amri ya git pull inapakua commit mpya kutoka repository ya mbali na kuziunganisha mara moja kwenye tawi lako la sasa — ni kitendo cha ndani kwenye terminal. Pull request ni ukurasa wa wavuti wa GitHub wenye pendekezo la kuunganisha tawi moja kwenye jingine.

Hakuna amri tofauti ya «git pull request» kwenye Git. Kuna zana ya zamani git request-pull, lakini inatengeneza tu maandishi ya barua pepe yenye muhtasari wa mabadiliko kwa ajili ya kutuma, na haihusiani na PR za GitHub.

Kwa nini pull request zinahitajika

Mradi unapofanywa na mtu mmoja, unaweza kucommit moja kwa moja kwenye main. Mara repository inapokuwa na watu wawili au zaidi, kutuma moja kwa moja kwenye tawi kuu kunakuwa chanzo cha ujenzi uliovunjika na kazi iliyopotea. Pull request inatatua kazi kadhaa kwa wakati mmoja:

• ukaguzi wa msimbo — mtu wa pili anaona mabadiliko kabla hayajaingia kwenye main, na anagundua makosa ambayo mwandishi alikosa;
• ukaguzi wa kiotomatiki — GitHub Actions au CI nyingine huendesha majaribio na linters kwa kila PR, na hali nyekundu inazuia kuunganisha msimbo uliovunjika;
• historia ya maamuzi — baada ya mwaka mmoja, kupitia PR unaweza kuelewa si tu kilichobadilishwa bali pia kwa nini, pamoja na majadiliano;
• kuchangia miradi ya wazi — kwenye open source huna ruhusa ya kuandika, na PR kutoka kwenye fork ndiyo njia pekee ya kupendekeza marekebisho;
• kulinda matawi — sheria za ulinzi wa tawi kwenye GitHub zinaweza kukataza kutuma moja kwa moja kwenye main na kudai PR iliyoidhinishwa.

Jinsi ya kuunda pull request kwenye GitHub kutoka tawi

Huu ndio mfumo mkuu kwa timu ambayo kila mtu ana ruhusa ya kuandika kwenye repository. Kazi inafanyika kwenye tawi la feature, na main inabadilika kupitia PR pekee.

Hatua ya 1. Unda tawi kutoka main ya hivi karibuni

git switch main
git pull
git switch -c feature/login-form

Jina la tawi liwe la maana: feature/…, fix/…, au namba ya kazi. Mkaguzi anaelewa papo hapo kinachohusika.

Hatua ya 2. Fanya commit

git add src/login.js
git commit -m "Ongeza fomu ya kuingia"

PR moja ni kazi moja. PR ndogo ya mistari 100–300 inakaguliwa haraka na kwa makini, lakini PR ya mistari 3000 mkaguzi anaidhinisha bila kuisoma.

Hatua ya 3. Tuma tawi kwenye seva (git push kwa pull request)

git push -u origin feature/login-form

Bendera -u inaunganisha tawi la kompyuta yako na tawi la mbali, na baada ya hapo git push rahisi inatosha. GitHub yenyewe itakupa kiungo cha kuunda PR kwenye jibu:

remote: Create a pull request for 'feature/login-form' on GitHub by visiting:
remote:      https://github.com/team/app/pull/new/feature/login-form

Hatua ya 4. Fungua PR kwenye kiolesura cha wavuti

Fungua kiungo kutoka kwenye terminal, au fungua repository kwenye GitHub: baada ya push mpya kunatokea bango lenye kitufe «Compare & pull request». Njia nyingine ni kichupo cha «Pull requests» na kitufe cha «New pull request».

1. Angalia jozi ya matawi: base — tunapounganisha (kwa kawaida main), compare — tawi lako.
2. Andika kichwa: kilichofanywa, kwa amri au kwa maelezo mafupi.
3. Kwenye maelezo, eleza kwa nini, jinsi ya kukagua, na kisichojumuishwa. Ikiwa repository ina kiolezo cha PR, sehemu zitajazwa zenyewe.
4. Upande wa kulia, weka wakaguzi (Reviewers), mhusika (Assignees), na lebo ikiwa timu inazitumia.
5. Bonyeza «Create pull request» au chagua rasimu (kuhusu hilo hapa chini).

Kuunda PR kutoka terminal: GitHub CLI

Ikiwa hutaki kubadili kwenda kwenye kivinjari, kuna zana rasmi ya gh. Si amri ya Git, bali programu ya GitHub, lakini kwa PR ni rahisi sana:

gh pr create --base main --title "Ongeza fomu ya kuingia" --body "Closes #42"
gh pr list
gh pr checkout 57
gh pr merge 57 --squash

Kwa swali «amri za git pull request», jibu la kweli ni hili: Git inashughulikia matawi, commit na push, lakini PR yenyewe inaundwa kwenye jukwaa — kwenye kivinjari, kupitia gh, au kupitia API.

Jinsi ya kutuma pull request kwenye repository ya mtu mwingine kupitia fork

Kwenye miradi ya wazi huna ruhusa ya kuandika. Kwa hiyo kwanza unafanya fork — nakala yako ya repository kwenye GitHub — unafanyia kazi huko, kisha unapendekeza mabadiliko kwa mradi wa asili.

1. Kwenye ukurasa wa mradi, bonyeza «Fork» — itaonekana github.com/you/project.
2. Clone fork yako na uongeze mradi wa asili kama remote ya pili, kwa kawaida inaitwa upstream.
3. Unda tawi, fanya commit na utume tawi kwenye fork yako.
4. Kwenye GitHub fungua PR: base repository — mradi wa asili, head repository — fork yako na tawi lako.

git clone git@github.com:you/project.git
cd project
git remote add upstream https://github.com/owner/project.git
git switch -c fix/typo-readme
git commit -am "Rekebisha kosa la tahajia kwenye README"
git push -u origin fix/typo-readme

Kabla ya kuanza, angalia faili la CONTRIBUTING.md: kwa kawaida huelezea sheria za kuandika commit, majaribio, na kama unahitaji kwanza kufungua issue. Weka fork yako ikiwa ya kisasa: git fetch upstream na git rebase upstream/main kwenye tawi lako, ili PR isiwe nyuma ya mradi asili.

Merge request kwenye GitLab: ni nini na jinsi ya kuunda

Merge request ya GitLab ni sawa kabisa na pull request ya GitHub. Majina na maelezo ya kiolesura yanatofautiana, lakini mchakato ni uleule: tawi, push, ombi la kuunganisha, ukaguzi, kuunganisha.

MR unaweza kuiunda kwa njia kadhaa:

• kupitia kiungo ambacho GitLab inachapisha kwenye terminal baada ya git push ya tawi jipya;
• kwenye sehemu ya Merge requests ya mradi, kwa kitufe cha «New merge request», ukichagua tawi la chanzo na lengwa;
• moja kwa moja wakati wa push, kwa kutumia push options za GitLab — bila kwenda kwenye kivinjari.

git push -o merge_request.create -o merge_request.target=main origin feature/login-form

Istilahi za GitLab zinatofautiana kidogo: idhini inaitwa approve, mtu anayehusika na kuunganisha ni assignee, na badala ya GitHub Actions kuna GitLab CI/CD yenye faili la .gitlab-ci.yml. Kuna pia rasimu za MR — zinaitwa Draft.

Ukaguzi wa pull request

Mkaguzi anafungua kichupo cha «Files changed» na kuona diff. Kwenye mstari wowote anaweza kuacha maoni au kupendekeza marekebisho tayari (suggestion), ambayo mwandishi anayatumia kwa bonyeza moja. Maoni yanakusanywa kwenye ukaguzi mmoja na kutumwa pamoja na mojawapo ya maamuzi haya:

• Comment — maoni tu bila uamuzi;
• Approve — mabadiliko yameidhinishwa;
• Request changes — yanahitaji marekebisho zaidi, kuunganisha hakupendekezwi.

Ukaguzi mzuri unaangalia mantiki, usomaji, majaribio na visa vya mipaka, badala ya kubishana kuhusu ladha. Mpangilio wa msimbo ni bora kumwachia linter kwenye CI. Mwandishi anapaswa kujibu kila maoni: amerekebisha, wamejadiliana, au anaacha hivyo kwa maelezo.

Jinsi ya kukagua PR ya mtu mwingine kwenye kompyuta yako (git checkout pull request)

Wakati mwingine msimbo unahitaji kuendeshwa kwenye kompyuta yako. Ikiwa tawi liko kwenye repository ileile, git fetch na git switch zinatosha. Kwa PR kutoka fork, GitHub inatoa viungo maalum pull/<namba>/head:

git fetch origin pull/57/head:pr-57
git switch pr-57

Kwenye GitLab viungo sawa vinaitwa merge-requests/<namba>/head. Au tumia tu gh pr checkout 57 ikiwa GitHub CLI imesakinishwa.

Jinsi ya kusasisha pull request baada ya maoni

PR inafungamana na tawi, si na commit mahususi. Fanya commit mpya kwenye tawi lilelile na uitume: PR itasasishwa yenyewe, bila kuunda ombi jipya.

git commit -am "Zingatia maoni ya ukaguzi"
git push

Git rebase pull request: kuvuta main ya hivi karibuni

PR ikiwa bado kwenye ukaguzi, main inasonga mbele. GitHub ikisema tawi limepitwa na wakati au kuna migongano, lisasishe. Njia ya rebase inatoa historia ya mstari mmoja:

git fetch origin
git rebase origin/main
# tatua migongano, git add, git rebase --continue
git push --force-with-lease

Baada ya rebase, hash za commit zinabadilika, kwa hiyo push ya kawaida itakataliwa — inahitajika push ya kulazimisha. Tumia --force-with-lease: itakataa kuandika juu ya tawi ikiwa kuna commit za mtu mwingine ndani yake. Ikiwa watu wengi wanafanya kazi kwenye tawi hilo, ni salama zaidi kuunganisha main kupitia git merge origin/main — bila kuandika upya historia.

Jinsi ya kuunganisha pull request: merge, squash na rebase

Ukaguzi ukishaidhinishwa na ukaguzi wa kiotomatiki ukiwa kijani, PR inaweza kuunganishwa. GitHub inatoa njia tatu, na msimamizi wa repository anaweza kuruhusu baadhi tu.

Merge pull request kupitia kiolesura ni kimsingi git merge ile ile, lakini inafanyika kwenye seva. Baada ya kuunganisha, GitHub inapendekeza kufuta tawi — kubali, kwa sababu halihitajiki tena. Kwenye kompyuta yako, safisha pia:

git switch main
git pull
git branch -d feature/login-form

PR pia inaweza kuunganishwa kwa mkono kutoka terminal: unaunganisha tawi kwenye main kwenye kompyuta yako kisha unatuma. GitHub itagundua kwamba commit za tawi zimefika kwenye base na itaweka PR kama merged yenyewe. Lakini kwa njia hiyo ukaguzi na sheria za ulinzi wa tawi zinapotea, ndiyo maana timu nyingi zinaunganisha kwa kitufe.

Auto-merge na merge queue

Ukaguzi ukichukua muda mrefu, unaweza kuwasha kuunganisha kiotomatiki: PR itaunganishwa yenyewe mara masharti yote yatakapotimia. Kwenye repository kubwa hutumiwa foleni ya kuunganisha (merge queue), inayokagua PR juu ya zile zilizo kwenye foleni, ili main isivunjike kwa sababu ya mabadiliko yasiyoendana.

Rasimu za pull request (Draft)

Rasimu ni PR ambayo bado haijawa tayari kwa ukaguzi. Haiwezi kuunganishwa, na wakaguzi hawapokei ombi la ukaguzi. Rasimu ni nzuri kuonyesha mwelekeo mapema, kuendesha CI, au kupata maoni kuhusu usanifu. Kwenye GitHub unapounda PR chagua chaguo la rasimu kwenye menyu ya kitufe cha kuunda, au tumia gh pr create --draft. Kazi ikishakamilika, bonyeza «Ready for review». Kwenye GitLab rasimu inaweka kiambishi Draft: mbele ya kichwa cha MR.

Kuunganisha pull request na issues

Ukiandika neno la ufunguo na namba ya kazi kwenye maelezo ya PR, baada ya kuunganisha GitHub itafunga issue kiotomatiki kwenye tawi kuu:

Closes #42
Fixes #17
Resolves #8

Maneno close, fix na resolve yanafanya kazi katika namna mbalimbali (closes, fixed, resolves). Kutaja tu #42 bila neno la ufunguo kunaunda kiungo, lakini kazi haifungwi. GitLab pia inaelewa Closes #42 na misemo inayofanana.

Je, pull request au merge request inaweza kufutwa

Mshiriki wa kawaida hawezi kufuta PR kwenye GitHub — anaweza tu kuifunga kwa kitufe cha «Close pull request». PR iliyofungwa inabaki kwenye historia, na inaweza kufunguliwa tena. Tawi baada ya kufunga lifutwe kando. Kufuta PR kabisa kunawezekana tu kupitia usaidizi wa GitHub, kwa mfano ikiwa siri (secrets) zimeingia humo.

Kwenye GitLab, MR inaweza kufungwa na mwandishi au mshiriki mwenye haki, na kufutwa na mmiliki wa mradi au msimamizi. Ikiwa nenosiri au token imeingia kwenye PR, kufunga hakutoshi: batilisha siri hiyo mara moja, kwa sababu commit tayari zilishafika kwenye seva.

Makosa ya kawaida kwenye pull request

• PR kutoka main. Umecommit kwenye main yako mwenyewe na kufungua PR kutoka humo. PR ijayo itakuwa na mabadiliko ya zamani pia. Fanya kazi kila mara kwenye tawi tofauti.
• Tawi la base lisilo sahihi. PR imefunguliwa kwenye develop badala ya main au kinyume chake. Base inaweza kubadilishwa kwa kitufe cha Edit karibu na kichwa cha PR.
• Faili zisizohitajika zimeingia kwenye diff. Build, node_modules, .env. Ziweke kwenye .gitignore na uziondoe kwenye index kwa git rm --cached.
• PR kubwa mno. Gawa kazi kuwa PR kadhaa mfululizo.
• Push ya kawaida baada ya rebase. Hitilafu rejected (non-fast-forward). Tumia git push --force-with-lease, si --force.
• Migongano. Usiyatatue kwa upofu kwenye kihariri cha wavuti — vuta main kwenye kompyuta yako, tatua, kisha jaribu msimbo.

Pull request kwenye git flow na michakato mingine

Pull request inafaa katika mchakato wowote wa timu. Kwenye GitHub Flow ni rahisi: tawi kutoka main, PR, ukaguzi, kuunganisha, kupeleka. Kwenye git flow, PR zinafunguliwa kwenye develop kutoka matawi ya feature, na matawi ya release na hotfix pia hupitia PR kwenda main. Kwenye trunk-based development PR ni fupi na huishi masaa, si siku. Bila kujali mchakato, kanuni ni moja: mabadiliko kwenye matawi ya pamoja yapitie pull request pekee.

Kwa ufupi

Pull request ni utaratibu wa jukwaa, si amri ya Git: tawi lililotumwa kwenye seva, pamoja na ukurasa wa majadiliano, ukaguzi na uthibitishaji. Kwenye GitLab ni merge request; kwenye mazungumzo tunasema PR na MR. Unda PR kutoka tawi tofauti, iweke ndogo, sasisha kwa kutuma kwenye tawi lilelile, na chagua njia ya kuunganisha inayoendana na historia ya mradi. Matawi ya feature, fork na pull request vimefafanuliwa kwa mifano halisi kwenye kozi ya Git.