Pull Request-lərin sehrı

1. Birleşdirmədən təklifə: Pull Request-lər nəyə görə lazımdır?

Ötən mühazirədə biz lokal kompüterimizdə branch-ları merge etməyi öyrəndik. Bu tək işləyəndə əladır. Amma layihədə bütün komandası işləyirsə nə olar? Əgər hər kəs dəyişikliklərini birbaşa əsas branch olan main-ə merge edərsə, çox keçmədən xaos yaranacaq: kimsə səhv kod əlavə edə, build-u poza və ya həmkarının vacib işini silə bilər.

Bunu qarşısını almaq üçün komandada başqa yanaşma var. Dəyişiklikləri dərhal merge etmə əvəzinə, siz merge təklifi yaradırsınız. Bu təklifə Pull Request (qısaca PR) deyilir, bəzi platformalarda isə Merge Request adlanır.

Pull Request — rəsmi bir xahişdir: "Zəhmət olmasa, mənim branch-imdən dəyişikliklərimi pull edib main-ə merge edin". Amma bu sadəcə xahiş deyil, kod main-ə daxil olmadan əvvəl müzakirə, yoxlama və təkmilləşdirmə üçün platformadır.

2. Pull Request ilə standart iş prosesi

Gəlin addım-addım yeni funksionallıq yaratmaq prosesinin necə göründüyünə baxaq.

Yeni task üçün branch yaratmadan əvvəl əmin olun ki, bütün tamamlanmış commit-lərinizi push etmisiniz və əsas main branch-ı Update Project ilə yeniləmisiniz.

Əks halda sizin "unutduğunuz" lokal commit-ləriniz təsadüfən yeni Pull Request-ə düşəcək və həmkarlar üçün qarışıqlıq yaranacaq.

1-ci addım. Yeni task üçün branch yaradın.

Əvvəlki kimi, hər yeni iş ayrı branch-dan başlayır. Tutaq ki, layihəyə contributorlar üçün qaydalar faylı əlavə etmək istəyirik. feature/add-contribution-guide adlı branch yaradaq.

2-ci addım. Dəyişiklik edin və branch-i GitHub-a göndərin.

Yeni branch-da CONTRIBUTING.md faylı yaradın (yaradandan sonra Add-a basın) və digər developer-lərə mesaj yazın. Sonra aydın mesajla Commit and Push edin, məsələn: docs: Add contribution guide.

Bu kritik addımdır! Pull Request uzaq serverdə artıq mövcud olan branch əsasında yaradılır. Ona görə PR yaratmazdan əvvəl yeni branch-inizi GitHub-a push etməlisiniz.

3. IntelliJ IDEA-dan Pull Request yaratmaq

İndi branch GitHub-da olduqda, Pull Request yaratmaq olar.

1-ci addım. Pull Requests tab-ını açın.

IDE-nin solunda Pull Requests tab-ı var. Onu açın və yeni PR yaratmaq üçün + ikonuna basın.

2-ci addım. PR üçün məlumatları doldurun.

IDE sizin üçün rahat interfeys açacaq. Sizin işiniz onu düzgün doldurmaqdır. Gəlin əsas sahələri nəzərdən keçirək:

1. Başlıq: IDE adətən buraya branch adını qoyur, amma bu pis praktikadır. Başlıq qısa, aydın və dəyişikliklərin mahiyyətini əks etdirməlidir, yaxşı commit mesajı kimi.
2. Təsvir: burada siz nə və niyə etdiyinizi izah edirsiniz.
3. Reviewers: burada kodunuzu yoxlamalı olan bir və ya bir neçə həmkar seçirsiniz. Tədris layihəsində bu addımı keçə bilərik, amma real işdə bu vacibdir.
4. Assignees: adətən burada özünüzü göstərirsiniz. Bu o deməkdir ki, siz müəllif və bu task-ın əsas məsulusunuz və review-dən sonra düzəlişləri siz edəcəksiniz.

Bütün sahələri doldurduqdan sonra Create Pull Request-ə basmaqdan çəkinməyin.

4. Code-review: yoxlama və müzakirə

PR yaradıldıqdan sonra ən vacib mərhələ başlayır — code review. Həmkarlarınız PR-ınızı açıb bütün dəyişiklikləri görə və şərh yaza bilərlər.

Siz bütün müzakirələri birbaşa IDE-də Pull Requests tab-ında görə bilərsiniz. Kimsə şərh yazsa, xəbərdarlıq alacaqsınız.

Əgər düzəliş etmək istəsələr nə etməli?

Çox sadədir! Yeni PR yaratmağa ehtiyac yoxdur. Eyni branch-də lazım olan düzəlişləri edin, yeni commit edin və push edin. GitHub-da olan Pull Request avtomatik olaraq sizin yeni commit-lərlə yenilənəcək.

5. İşin tamamlanması: merge və branch-in silinməsi

Bütün rəy və düzəlişlər tamamlanıb komanda dəyişikliklərinizi təsdiq etdikdə, Pull Request-ı merge etmək olar. Adətən bunu senior developer edir və ya əgər sizdə icazə varsa, özünüz edə bilərsiniz.

1-ci addım. Merge

Merge əksər hallarda GitHub saytında olur. PR-inizin altında böyük yaşıl Merge pull request düyməsi görünəcək. Ona basdıqdan sonra kodunuz əsas branch olan main-in bir hissəsi olacaq.

2-ci addım. Branch-in silinməsi.

Merge-dən sonra sizin feature-branch-ə artıq ehtiyac yoxdur və repository-ni qarışdırmamaq üçün onu silmək yaxşıdır. GitHub bunu təklif edəcək və Delete branch düyməsini göstərəcək.

IDE-də lokal branch nüsxəsini də silməyi unutmayın ki, nizam olsun. Bunu branch idarəetmə menyusundan etmək olar.

6. Üç commit qaydası

Yaxşı commit yalnız düzgün mesaj deyil, həm də düzgün məzmun deməkdir. Dəyişiklik tarixçənizin təmiz, faydalı və peşəkar olması üçün üç sadə qaydaya əməl edin.

Qayda 1: standart üzrə aydın mesajlar yazın

Sizin commit-lər komandanıza və öz gələcəyinizə göndərdiyiniz mesajlardır. "fix" və ya "update" kimi mesajlarla dolu tarixçə heç faydalı deyil. Ən populyar standart Conventional Commits adlanır. O aşağıdakı strukturu təklif edir:

<type>: <qısa təsvir>

Type — dəyişiklik kateqoriyasını təsvir edən qısa sözdür:

• feat: (feature) — yeni funksionallıq üçün.
• fix: — səhv düzəlişi üçün.
• docs: — sənədləşmədə dəyişikliklər üçün.
• style: — kod loqikasına təsir etməyən formatlama düzəlişləri üçün.
• refactor: — yeni funksionallıq əlavə etməyən və səhvləri düzəltməyən kod dəyişiklikləri üçün.
• test: — testlərin əlavə edilməsi və ya düzəldilməsi üçün.
• chore: — asılılıqların yenilənməsi, build konfiqurasiyası kimi rutin işlər üçün.

Nümunələr:

• Pis: fixed bug
• Yaxşı: fix: Correct user login validation

• Pis: readme
• Yaxşı: docs: Update installation instructions

Qayda 2: bir commit — bir məntiqi dəyişiklik (Atomiklik)

Bir commit-ə eyni vaxtda bug fix, yeni funksiya və köhnə kodun refaktorunu sığışdırmağa çalışmayın. Belə commit-i yoxlamaq çətindir və nəsə səhv olsa geri qaytarmaq demək olar ki, qeyri-mümkündür.

Hər commit yalnız bir konkret vəzifəni həll etməlidir.

• Pis: "Update user page" mesajlı bir commit, hansı ki avatar sahəsi əlavə edir, istifadəçi adı validasiyasında səhvi düzəldir və düymələrin rəngini dəyişir.
• Yaxşı: üç ayrı commit:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

Kiçik, fokuslanmış commit-lər anlamaq və idarə etmək üçün daha asandır.

Qayda 3: Commit layihəni pozmamalıdır

Əsas branch-dakı hər commit layihəni işlək vəziyyətdə saxlamalıdır. Commit yaratmazdan əvvəl ən azı kodun compile olduğunu yoxlamalısınız. Amma başqa hissəni təsadüfən pozmadığınızdan necə əmin olmaq olar? Yalnız manual yoxlamaya güvənmək risklidir.

Burada avtomatlaşdırma köməyə gəlir. Bu kursda avtomatik prosesləri qurmayacağıq, amma real layihələrdə necə işlədiyini bilməlisiniz. Müasir komandalar Continuous Integration (CI) sistemlərindən, məsələn GitHub Actions-dan istifadə edirlər.

Necə işləyir?

Siz kod və ona aid testlər yazırsınız. Sonra GitHub-da xüsusi bir workflow qurursunuz. İndi siz push etdikdə PR-a bu sehr baş verir:

1. GitHub Actions bu eventi görür və sizin workflow-u işə salır.
2. O avtomatik layihəni "build" edir və bütün testləri işə salır.
3. Əgər bütün testlər uğurla keçərsə, GitHub-da sizin commit-in yanında yaşıl işarə görünür. Bu komandaya dəyişikliklərin təhlükəsiz olduğunu bildirir.
4. Əgər ən azı bir test uğursuz olarsa, siz qırmızı çarpı görəcəksiniz. Belə PR-i əsas branch-ə merge etmək qəti qadağandır.

            graph LR
            subgraph GitHub
            A[İnkişaf etdirici] -- "push" --> B(Repository)
            B -- "Hadisə: push" --> C{GitHub Actions}
            end

            subgraph Workflow
            C -- "İşə salma" --> D[Run_tests]
            D --> E[Uğurla]
            D --> F[Uğursuz]
            end

            subgraph Notifications
            F --> G((Email))
            G --> H[İnkişaf etdirici]
            G --> I[Komanda]
            end

            style F fill:#f99,stroke:#333,stroke-width:2px
            style G fill:#ccf,stroke:#333,stroke-width:2px
        

Bildirişləri tənzimləmək olar. Əgər testlər uğursuzdursa, GitHub Actions sizə və ya bütün komandaya e-mail göndərə bilər. Belə yanaşma testlərin sadəcə formal yox, inkişaf prosesinin əvəzsiz hissəsi olduğu mədəniyyətini yaradır və hər kəs öz kodunun keyfiyyətinə görə məsuliyyət daşıyır.