Gerrit/İleti yönergeleri sunma
Bu sayfa, zaman içinde geliştirici fikir birliği tarafından (veya bazen bir potansiyel geliştiriciden bildiri yoluyla) oluşturulan bir MediaWiki geliştirme yönergesi belgesini belgelemektedir. |
Yaptığınız değişikliğin taahhüt mesajı önemli bir rol oynar. Diğer insanların sizin değişikliğiniz hakkında ilk görecekleri şey.
component: Short subject line
More details. The blank line between the subject and body is
mandatory. The subject line is used to represent the commit in
code-review requests, search results, git rebase, logs, and more.
Bug: T54321
Yapı
Konu
İşlem mesajının ilk satırı konu olarak bilinir. Konu 80 karakterden kısa olmalıdır (50-70 hedefi).
- Konu satırındaki değişikliğinizi özetleyin. Bunun sonsuza kadar depoda olacağını unutmayın.
- İsteğe bağlı olarak, konunun önüne ilgili bileşen öneki ekleyin. Bileşen, taahhüdünüzün değişeceği genel alandır.
- Konu satırınızdaki zorunlu ruh hâlini kullanın. Avoid stating a fact, like "Badge hides zero" or "Zero in badges", which is ambigious and does not describe a change (good or bad? before or after?). Consider instead "Hide zeroes in badges", "Show zeroes in badges", or "Badge: Restore display of zero".
Zorunlu ruh hâli, birisine talimat veriyormuşsunuz gibi geliyor ve "Değiştir", "Düzelt", "Ekle", "Kaldır", "Belge", "Yeniden Düzeltme" gibi kelimelerle başlayabilir. - Your subject line should be short, clearly state what your commit is changing.
It should not be possible to use the same subject line for two commits that do different things. Consider "Fix FooBar docs to use @chainable" instead of "Fix a function doc". People will read your subject line out of context, as it passes by in change feeds, code review emails, git-blame logs, release notes, deployment changelog, etc. A good subject line helps decide quickly whether this commit among many will be relevant to a given interest or concern. - Konu satırını nokta/tam nokta (
.
) ile sonlandırmayın.
İyi örnekler, "API'yi sorgulamak için Badge::query ekle", "SimpleBadge içinde API sorgusunu önleyin" ve "SimpleBadge::add'de sıfırları destekleyin". | Kötü örnekler "Badge::query yöntemi eklendi", "Badge::sorgu yöntemi düzeltildi", "Rozet API'yi sorgulayabilir", "Rozet API sorguları yapmaz" veya "Rozet eklerken sıfırlar çalışır" olurdu. |
---|---|
|
|
Gövde
Gövde metnini yazarken aşağıdaki soruları düşünün:
- Bu değişiklik neden yapılmalıdır? Mevcut kodda sorun nedir?
- Neden bu şekilde değiştirilmeli? Başka yollar var mı?
- Başka yaklaşımlar düşündünüz mü? Öyleyse, neden bu kadar iyi olmadıklarını açıklayın.
- Bir yorumcu kodunuzun doğru çalışıp çalışmadığını nasıl test edebilir veya doğrulayabilir?
Recommended:
- … gövdeyi özneden bir boş satırla ayırın.
- … mesajı satırlar maksimum 100 karakter uzunluğunda olacak şekilde sarın. Many editors/tools can do this automatically; 72 characters is a common width to wrap at.[1] Ancak, URL'leri 'uydurmak' için bozmayın, çünkü bu onları tıklanamaz hâle getirir; daha uzun olsalar bile onları saklayın.
I83f83377f2
gibi (kısa) bir Gerrit Change-Id veya51e3fb9a71
gibi Git commit hash kullanarak diğer taahhütlere bakın. İlgili değişiklik henüz birleştirilmediyse, Git taahhüt karması birleştirildikten sonra değişeceğinden, her zaman Gerrit Change-Id kullanın, bu da çıkmaza yol açar.
Not recommended:
- Don't refer to other commits with a URL or change number.
- Instead, use the Gerrit Change-Id like
I83f83377f2
or Git commit hash like51e3fb9a71
. This kind of hash is automatically converted to a link when viewing the change in Gerrit, Gitiles, and other repository browsers. Ayrıca,git show
veya dahili metin düzenleyiciler gibi geliştirme sırasında Git deposunda kolay gezinmeye olanak tanır. - Öte yandan, bir URL yalnızca bir web tarayıcısında çözülebilir ve kod inceleme iş akışlarını bozan ve yerel bağlamdan ayrılan sabit bir konuma gider. For example, inside a Git browser the hash allows you to quickly go from one commit to a related one in the same tool, instead of being sent to Gerrit. The hashes can also be searched for in Gerrit to automatically find commits that refer to it.
- Another issue is that change numbers can ambiguous or become automatically linked to a different commit than you intend. This is because commit hashes are sometimes numbers only, e.g. commit 665661 is different than change 665661.
- Instead, use the Gerrit Change-Id like
- Bir değişikliğin açıklaması olarak yalnızca bir URL kullanmayın.
- Değişiklik, başka bir yerde yapılan bir tartışma veya bazı harici belgeler tarafından gerekçelendiriliyorsa, taahhüt mesajınızdaki önemli noktaları özetlemeye çalışın ve URL'ye de bakın.
Footer and meta-data
The most important information of the footer is the Change-Id
(mandatory) and Bug
.
- Aşağıdaki örneklerde olduğu gibi "
Bug
" ve "Change-Id
" meta verilerini biçimlendirin ve boş bir satırdan sonra bunları gövdenin sonuna yerleştirin.
Find more information on individual meta-data fields below.
Örnekler
İyi örnek
jquery.badge: Add ability to display the number zero Cupcake ipsum dolor sit. Amet tart cheesecake tiramisu chocolate cake topping. Icing ice cream sweet roll. Biscuit dragée toffee wypas. Does not yet address T44834 or T176. Follow-up to Id5e7cbb1. Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907
Kötü örnek
Improved the code by fixing a bug. Changed the files a.php and b.php Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907
Ek bilgi
.gitmessage
file (example), use the following command to get a template to guide you in writing a commit message: git config commit.template=.gitmessage
Konu
Git komutunu görüntülediğimiz çoğu program, konu satırını düz metin olarak işler. Bu, URL'lerin çalışmadığı ve metnin sıklıkla seçilmesi/kopyalanmasının mümkün olmadığı anlamına gelir. Bu nedenle, konu satırında Phabricator görevlerinden, Git taahhütlerinden veya URL'lerinden bahsetmeyin. Bunun yerine, gövde metninden veya altbilgi meta verilerinden bahsedin. Bu şekilde, evrensel olarak seçilebilir, kopyalanabilir veya tıklayabilirler.
- Gerrit şu konuyu kullanır: e-posta bildirimleri, IRC bildirimleri, arama sonuçları.
- GitHub şu konuyu kullanır: kesinleştirme geçmişi, kesinleştirme konusu.
- Git CLI aşağıdaki konuyu kullanır:
git shortlog
,git log --oneline
,git rebase -i
,git show
, etc. - MediaWiki'nin Wikimedia dağıtım dallarının sürüm notları
- ve daha fazlası!
Bileşen
Konu satırına, taahhüdünüz tarafından projenin hangi alanının değiştirildiğini belirten bir bileşenle başlayabilirsiniz.
Aşağıdakilerden biri olmalıdır:
- "installer", "jobqueue", "objectcache", "resourceloader", "rdbms", vb. gibi
includes/
veyaincludes/libs
altındaki PHP sınıfları dizini - "Title", "User", "OutputPage", vb. gibi bir PHP sınıf adı; tipik olarak
includes/
içinde alt dizini olmayan sınıflar için. - ResourceLoader modül adı ("mediawiki.Title", "mediawiki.util", vb. gibi).
- Değişiklik türüyle ilgili birden çok alanı etkileyen genel anahtar kelime, örneğin:
- "build" -
package.json
,.travis.yml
, vb. güncellemeleri gibi geliştirme iş akışıyla ilgili dosyalarda yapılan değişiklikler için - "tests" or "test" (depending on directory name) - yalnızca birim veya entegrasyon test takımlarını veya test takımı çalıştırıcılarını etkileyen değişiklikler için.
- "build" -
Phabricator
Phabricator bir hataya veya göreve başvurmak için, taahhüt mesajında Txxx gösterimini kullanarak satır içinde belirtin (ör. "That was caused by T169.")
Bir taahhüdün çözüldüğünü (kısmen de olsa) veya bir hatayla özellikle ilgili olduğunu ifade etmek için, taahhüt mesajının sonuna altbilgiye Bug: Txxx
ekleyin.[2]
(Bir işlem mesajını değiştiriyorsanız, bunu, aralarında boş bir satır olmadan Change-Id:
satırının hemen üstüne ekleyin. Genel yapı kurallarına uymayı ve gövdeyi konudan bir boş satırla ayırmayı unutmayın.)
Bug: T169
Bir bot otomatik olarak Phabricator'ın görevi hakkında önemli olaylar (birleştirilmiş, terk edilmiş vb.) hakkında bir yorum bırakacaktır.
Bir yama iki veya daha fazla hatayı giderirse, her Bug: T12345
kaynağı altta kendi satırına koyun.
Bug: T299087 Bug: T299088
Çapraz kaynaklar
Ne zaman başka bir işleme başvurursanız, birleştirilmiş işlemin SHA-1 git karmasını kullanın. Hâlâ incelenmeyi bekliyorsa, git ayrı karması yerine Gerrit Change-Id karmasını kullanın, çünkü karma ayrı bir yama kümesiyle ilgilidir (yeniden temel alındığında değişir, böylece çıkmaz oluşturur).
Change-Id
Gerrit 'in git-review
aracı otomatik olarak "Change-Id: Ixxx
" anahtar kelimesini yeni taahhütlere ekleyecektir.
Bağımlılıklar
Depends-On: Ixxx
Çapraz repo bağımlılığı (taahhüdünüz farklı bir depodaki başka bir işleme bağlıysa) varsa, son paragrafa Depends-On: Ixxx...
ekleyerek bunları beyan edin.
("Ixxx"... diğer taahhütlerin Change-Id
.)
Bu Zuul'a taahhüdü bununla birlikte test etmesini söyleyecektir.
To provide additional guidance to developers, you can indicate the inverse relationship using Needed-By: Iyyy...
in last paragraph of the commit message in the other repository.
("Iyyy"... is the Change-Id
of your commit.)
Note that Zuul does not react to this, it is just for the benefit of human readers.
Also, Gerrit will automatically add backlinks based on the presence of Depends-On
, regardless of any Needed-By
.
Başkalarına katkı vermek
Co-Authored-by: gerrit_username <gerrit_user_email@example.com>
Değişiklik üzerinde çalışan diğer geliştiricilere katkı vermek için bu satırı Change-id'den önce ekleyin. Satır sonu ile ayrılmış birden fazla ekleyebilirsiniz.
by
is not capitalised; it's Co-Authored-by
, not Co-Authored-By
.
Daha fazla okuma
- Manual:Coding conventions#Release notes
- commit-message-validator
- Gerrit Commit Guidelines
- Node.js Taahhüt Kuralları
- Git Temel Taahhüt Kuralları
- jQuery Taahhüt Kuralları
- Erlang Taahhüt Kuralları
- Git Tamamlama Mesajları Hakkında Bir Not - Tim Pope tarafından
- Git Tamamlama Mesajı Nasıl Yazılır - Chris Beams tarafından
- Gerrit integrations with the Puppet Catalogue Compiler
Kaynakça
- ↑ This is a legacy from times when lines were provided on punched cards. Columns 1 to 72 where used for the statement and columns 73 to 80 for short comments. Size 72 is reasonable enough to understand the code at first glance.
- ↑
Tüm üstbilgi/altbilgilerde olduğu gibi, adı tek tek büyük harfle yazılmış ve aralarında tireler (örneğin,
Hypothetical-Header-Or-Footer
) yazın. Adı iki nokta üst üste (":"), ardından bir boşlukla izleyin. Git işlemine benzer şekilde, HTTP ve E-posta üstbilgileri gibi, altbilginin üzerine fazladan boş satırlar eklenmesi altbilgiyi keser ve eski bölümü gövdeye yanlış ekler.