Git-ის სტილისტიკის სახელმძღვანელო

დედანი: Agis/Git-Style-Guide

სარჩევი

1. განშტოებები
2. ქომითები
   • შეტყობინებები
3. შერწყმა
4. სხვადასხვა
5. ლიცენზია

განშტოებები (Branches)

• შეარჩიეთ მოკლე და აღწერითი სახელები:

  # კარგია
  $ git checkout -b oauth-migration
  
  # ცუდია - ძალიან ბუნდოვანია
  $ git checkout -b login_fix

• იდენტიფიკატორები შესაბამისი გარე სერვისებიდან (მაგ. Github issue) ასევე მშვენიერი კანდიტატები არიან განშტოების სახელებში გამოსაყენებლად. მაგალითად:

  # GitHub issue #15
  $ git checkout -b issue-15

• განშტოებათა სახელის ჩაწერისათვის გამოიყენეთ პატარა ასოები. გარე სერვისთა იდენტიფიკატორების დიდი ასოებით ჩაწერა დასაშვები გამონაკლისია. სიტყვების ერთმანეთისაგან გამოსაყოფად გამოიყენეთ დეფისები.

  $ git checkout -b new-feature      # კარგია
  $ git checkout -b T321-new-feature # კარგია (Phabricator task id)
  $ git checkout -b New_Feature      # ცუდია

• როდესაც ერთსა და იმავე ფუნქციონალზე რამდენიმე ადამიანი მუშაობს, შესაძლოა მოსახერხებელი იყოს, თუკი თითოეულისათვის გამოყოფილი იქნება პირადი განშტოება და ცალკე იქნება გამოყოფილი მთელი გუნდისათვის საერთო განშტოება. გამოიყენეთ სახელდების შემდეგი კანონზომიერება:

  $ git checkout -b feature-a/main   # მთელი გუნდისათვის საერთო განშტოება
  $ git checkout -b feature-a/maria  # მარიას პირადი განშტოება
  $ git checkout -b feature-a/nick   # ნიკის პირადი განშტოება

  სურვილისამებრ მოახდინეთ პირად განშტოებათა შერწყმა მთელი გუნდისათვის საერთო განშტოებასთან (იხ. „შერწყმა“). საბოლოოდ, მოხდება მთელი გუნდისათვის საერთო განშტოების შერწყმა მთავარ („main“) განშტოებასთან.

• შერწყმის შემდეგ წაშალეთ განშტოება, თუკი არ გაქვთ მისი არწაშლის კონკრეტული მიზეზი.

  რჩევა: გაუშვით შემდეგი ბრძანება მთავარ („main“) განშტოებაზე ყოფნისას, რათა იხილოთ [მასთან] შერწყმულ განშტოებათა სია:

  $ git branch --merged | grep -v "\*"

ქომითები (Commits)

• თითოეული ქომითი უნდა წარმოადგენდეს ერთ ლოგიკურ ცვლილებას. ნუ გააერთიანებთ რამდენიმე ლოგიკურ ცვლილებას ერთ ქომითში. მაგალითად, თუ გამოასწორეთ ხარვეზი და გააუმჯობესეთ წარმადობა, უმჯობესია, ცვლილებები დაყოთ ორ დამოუკიდებელ ქომითად.

  რჩევა: გამოიყენეთ git add -p [ბრძანება] მოდიფიცირებულ ფაილთა ცალკეული ნაწილების ინტერაქტიულად ორგანიზებისათვის.

• არ დაყოთ ერთი ლოგიკური ცვლილება რამდენიმე ქომითად. მაგალითად, ფუნქციონალის რეალიზაცია და [მისთვის] სათანადო ტესტები უნდა გაერთიანდეს ერთსა და იმავე ქომითში.

• განახორციელეთ ქომითები დროულად და ხშირად. მოკლე, თვითმყოფადი ქომითები მეტად მარტივად გასაგებია და ამარტივებს უწინდელ მდგომარეობაში დაბრუნებას, თუკი რაიმე არასწორად წარიმართება.

• ქომითები ლოგიკური თანმიმდევრობით უნდა განხორციელდეს. მაგალითად, თუ X-ქომითი დამოკიდებულია Y-ქომითში განხორციელებულ ცვლილებებზე, მაშინ Y-ქომითი უნდა განხორციელდეს X-ქომითამდე.

შენიშვნა: ვიდრე მარტოდმარტო მუშაობთ ადგილობრივ (ლოკალურ) განშტოებაზე, რომლის ატვირთვაც (push) ჯერჯერობით არ მომხდარა, დასაშვებია ქომითების, როგორც თქვენი ნამუშევრის დროებითი ჩანაწერების, გამოყენება. თუმცა, ისევ და ისევ მართებულია ზემოთ მოყვანილი რეკომენდაციების დაცვა, სანამ ატვირთვას მოახდენდეთ.

შეტყობინებები (Messages)

• ქომითის აღწერისას გამოიყენეთ რედაქტორი, და არა ბრძანებათა სტრიქონი (ტერმინალი):

  # კარგია
  $ git commit
  
  # ცუდია
  $ git commit -m "Quick fix"

  ქომითისათვის ბრძანებათა სტრიქონის (ტერმინალის) გამოყენება გზღუდავთ, გიწევთ ყველაფრის ერთ ხაზში ჩატევა, რაც, ჩვეულებრივ, შეტყობინებებს არაინფორმაციულსა და ბუნდოვანს ხდის.

• სათაური (ანუ შეტყობინების პირველი ხაზი) უნდა იყოს აღწერითი, მაგრამ ლაკონიური. იდეალურ შემთხვევაში, იგი უნდა შედგებოდეს არაუმეტეს 50 სიმბოლოსაგან. ჩანაწერი უნდა იწყებოდეს დიდი ასოთი და დაიწეროს აწმყო დროში, იმპერატიულად. [წინადადების] ბოლოს წერტილს ნუ დასვამთ, რადგან ფაქტობრივად სათაურს წერთ:

  # კარგია - აწმყო დროშია, იმპერატიულია, დიდი ასოთი იწყება, შედგება 50-ზე ნაკლები სიმბოლოსაგან
  Mark huge records as obsolete when clearing hinting faults
  
  # ცუდია
  fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.

• ამის შემდეგ უნდა მოდიოდეს ცარიელი სტრიქონი, რომელსაც მოსდევს უფრო საგულდაგულო აღწერა. აღწერა უნდა შედგებოდეს [არაუმეტეს] 72 სიმბოლოსაგან და უნდა განმარტავდეს, თუ რატომ იყო საჭირო ცვლილებები, როგორ მოხდა პრობლემის გადაჭრა და რა გვერდითი მოვლენები შეიძლება მოჰყვეს ამას.

  საგულდაგულო აღწერაში ასევე მოცემული უნდა იყოს ინფორმაცია გამოყენებული რესურსების შესახებ (მაგ. შესაბამისი შეცდომის/პრობლემის (issue) ბმული):

  Short (50 chars or fewer) summary of changes
  
  More detailed explanatory text, if necessary. Wrap it to
  72 characters. In some contexts, the first
  line is treated as the subject of an email and the rest of
  the text as the body.  The blank line separating the
  summary from the body is critical (unless you omit the body
  entirely); tools like rebase can get confused if you run
  the two together.
  
  Further paragraphs come after blank lines.
  
  - Bullet points are okay, too
  
  - Use a hyphen or an asterisk for the bullet,
    followed by a single space, with blank lines in
    between
  
  The pointers to your related resources can serve as a footer
  for your commit message. Here is an example that is referencing
  issues in a bug tracker:
  
  Resolves: #56, #78
  See also: #12, #34
  
  Source: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
  

  მარტივად რომ ვთქვათ, როდესაც ქომითის შეტყობინებას წერთ, უნდა დაფიქრდეთ იმაზე, თუ რისი ცოდნა შეიძლებოდა დაგჭირვებოდათ, თუკი ამ ქომითს ერთ წელიწადში წააწყდებოდით.

• თუკი A-ქომითი დამოკიდებულია B-ქომითზე, ეს დამოკიდებულება უნდა აღიწეროს A-ქომითის შეტყობინებაში. ქომითებზე მითითებისას გამოიყენეთ SHA1-ჰეში.

  ანალოგიურად, თუ A-ქომითი წყვეტს B-ქომითის მიერ წარმოქმნილ პრობლემას, ამის ფორმულირებაც A-ქომითის შეტყობინებაში უნდა მოხდეს.

• თუკი ქომითი უნდა გაერთიანდეს (squash) სხვა ქომითთან, გამოიყენეთ --squash და --fixup არგუმენტები სათანადოდ, რათა [თქვენი] მიზანი უფრო ნათელი გახადოთ:

  $ git commit --squash f387cab2

  (რჩევა: რებაზირების (rebasing) დროს გამოიყენეთ --autosquash არგუმენტი. [ამით,] მონიშნული ქომითები ავტომატურად გაერთიანდება.)

შერწყმა (Merging)

• ნუ მოახდენთ გამოქვეყნებული ისტორიის გადამუშავებას. საცავის (repository) ისტორია თავისთავად ღირებულია და ძალიან მნიშვნელოვანია შეგეძლოთ იმის დანახვა, თუ რა მოხდა სინამდვილეში. გამოქვეყნებული ისტორიის ცვლილება პრობლემათა გავრცელებული წყაროა ყველასთვის, ვინც პროექტზე მუშაობს.

• თუმცა, არსებობს შემთხვევები, როდესაც ისტორიის გადამუშავება ლეგიტიმურია. მაგალითად:

  • როდესაც განშტოებაზე მხოლოდ თქვენ მუშაობთ და მისი (განშტოების) განხილვა არ მოხდება.

  • როდესაც გსურთ, რომ მოაწესრიგოთ თქვენი განშტოება (მაგ. გააერთიანოთ ქომითები) ან/და ახდენთ მის რებაზირებას „main“ განშტოებაზე, რათა მოგვიანებით მოახდინოთ [მათი] შერწყმა.

  როგორც ითქვა, არასოდეს შეიტანოთ ცვლილება „main“ განშტოების ან ნებისმიერი სხვა სპეციალური დანიშნულების მქონე (მაგალითად, CI-სერვერების მიერ გამოყენებული) განშტოებების ისტორიაში.

• შეინარჩუნეთ ისტორიის სისუფთავე და სიმარტივე. ვიდრე განშტოების შერწყმას მოახდენდეთ:

  1. დარწმუნდით, რომ იგი შეესაბამება წინამდებარე სახლემძღვანელოს მითითებებს, ხოლო თუ ეს ასე არ არის, შეასრულეთ ნებისმიერი საჭირო მოქმედება [ამის გამოსასწორებლად] (გააერთიანეთ ქომითები ან შეცვალეთ მათი თანმიმდევრობა, ხელახლა უზრუნველყავით შეტყობინებები და სხვ.).

  2. მოახდინეთ მისი რებაზერიბა იმ განშტოებაზე, რომელთანაც შემდგომში მისი შერწყმა უნდა მოხდეს:

     [my-branch] $ git fetch
     [my-branch] $ git rebase origin/main
     # შემდგომ ამისა, მოახდინეთ შერწყმა

     შედეგად ვიღებთ ძალიან მარტივ ისტორიას და განშტოებას, რომელიც შესაძლებელია გამოყენებულ იქნეს უშუალოდ „main“ განშტოების ბოლოში.

     (შენიშვნა: ეს მეთოდი უკეთ შეეფერაბა მოკლევადიანი განშტოებებისაგან შემდგარ პროექტებს. სხვა შემთხვევებში შესაძლოა უმჯობესი იყოს, პერიოდულად მოახდინოთ „main“ განშტოების შერწყმა, მასზე რებაზირების ნაცვლად.)

• თუკი თქვენი განშტოება შეიცავს ერთზე მეტ ქომითს, არ მოახდინოთ შერწყმა დაჩქარებულად (fast-forward):

  # კარგია - იძლევა გარანტიას, რომ შერწყმის ქომითი შეიქმნა
  $ git merge --no-ff my-branch
  
  # ცუდია
  $ git merge my-branch

სხვადასხვა (Misc.)

• არსებობს მთელი რიგი შრომითი პროცესები (workflow-ები) და თითოეულს გააჩნია თავისი ძლიერი და სუსტი მხარეები. შეესაბამება თუ არა ესა თუ ის შრომითი პროცესი თქვენს შემთხვევას დამოკიდებულია თქვენს გუნდზე, პროექტზე და დეველოპმენტის თქვენებურ მეთოდიკაზე.

  ასე რომ, მნიშვნელოვანია შეარჩიოთ შრომითი პროცესი და გულმოდგინეთ მიჰყვეთ მას.

• იყავით თანმიმდევრული. ეს შრომით პროცესს ეხება, მაგრამ ასევე ვრცელდება ისეთ საკითხებზე, როგორიცაა — ქომითის შეტყობინებები, განშტოებათა სახელები და ტეგები. საცავის მასშტაბით თანმიმდევრული სტილის არსებობა გაგიმარტივებთ სამუშაოს პროგრესის იდენტიფიცირებას.

• მოახდინეთ ტესტირება, ვიდრე ატვირთავთ. ნუ ატვირთავთ სანახევროდ შესრულებულ ნამუშევარს.

• გამოიყენეთ ანოტირებული ტეგები გამოშვებათა (release-თა) ან სხვა მნიშვნელოვანი პუნქტების ისტორიაში აღნიშვნისათვის. უპირატესობა მიანიჭეთ მსუბუქ ტეგებს პირადი გამოყენებისათვის, როგორიცაა ქომითების ჩანიშვნა სამომავლო მითითებისათვის (reference).

• თქვენი საცავების კარგ ფორმაში შენარჩუნებისათვის პერიოდულად შეასრულეთ მოვლით-შენახვითი სამუშაოები:

  • git-gc(1)
  • git-prune(1)
  • git-fsck(1)

ლიცენზია

This work is licensed under a Creative Commons Attribution 4.0 International license.