Taahhüt tarihi, geliştiricilere kritik bilgileri iletmek için kullanılmalı mı?

Üçüncü taraf bir SDK’nın en son sürümden geri alınmasıyla ilgili bir toplantıda, geliştiricilerimizin taahhüt geçmişinde en son sürümün kullanılmaması gerektiğine işaret ettikleri belirtildi.

Bazı geliştiriciler bunun kötü bir uygulama olduğunu ve bunun kaynak dosyada (yani // Don't upgrade SDK Version x.y.z, see ticket 1234) ya da proje düzeyinde bir READMEdosyada belirtilmesi gerektiğini savundu . Diğerleri, taahhüt tarihi proje dokümantasyonunun bir parçası olduğu için, böyle bir bilgi için kabul edilebilir bir yer olduğunu, çünkü hepimizin okuması gerektiğini savundu.

Teslim geçmişi, kritik bilgileri diğer geliştiricilere iletmek için mi kullanılmalı yoksa bu bilgiler proje READMEveya yorumlar gibi ilgili kaynak dosyadaki başka bir yere kopyalanmalı mı?

Bir üçüncü taraf SDK'nın daha yeni bir sürümüne geçmeyi planlayacak olsam, en son baktığım yer kaynak kontrol sisteminin tarihidir .

Ürününüz bir SDK'nın 2.0 sürümünü kullanıyorsa ve birileri 3.0'a yükseltme yapmak istiyorsa, kaynak kontrol sisteminizde iyi bir fikir olmadığını anlamak için zaman içinde geriye bakmaları gerektiğini düşünmenin makul olduğunu sanmıyorum.

Burada, her geliştiricinin okuduğu ilginç bilgilerin yer aldığı bir avuç dolusu sayfalara sahip bir ekip wiki'miz var (kodlama kuralları, ürünü oluşturmak için bir geliştirme ortamının nasıl kurulacağı, hangi üçüncü taraf malzemeyi yüklemeniz gerektiği vb.). Bu, bir üçüncü taraf kütüphanesinin yükseltilmesine karşı bir uyarı için uygun olacak yer türüdür.

Taahhüt tarihinde belirtilmelidir, ancak bildirimi koyabileceğiniz en iyi yer, bağımlılığı tanımladığınız yerdedir. Örneğin yapay bağımlılıklarınızı bildiren bir maven .pom dosyanız varsa, şöyle bir şey yaparım:

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

Doğrudan <dependency>hattınızın üstünde .

# 123 no.lu sayı, çökmesine neden olan ayrıntıları, güncellediğiniz sürümü çökmelere neden olan ayrıntıları içerecek ve daha sonra tekrar ziyaret etmek için büyük olasılıkla tekrar biriktirme belgenize eklenmelidir. Ya bileti düzenleyerek ya da kendiniz el ile otomatik olarak, şu anki sorunu öğrenmelerini sağlamak için takıma e-posta gönderir ve izleyicide olmak, insanların daha sonra tekrar bulmalarına izin verir.

Bağımlılık bildirgesine koymanın nedeni, sürümü değiştirmek isteyenlerin, değiştirmek istedikleri anda görecekleri ve neden yapmamaları gerektiğini anlamalarıdır.

Kaynak kodda yorum yapmam, çünkü birisinin bağımlılıklarınızı kontrol ettiği ve yükseltmeye başladığı bir durumu kolayca hayal edebilirim. Bunu yapmak için her TODO yorumunun kod tabanını incelemeleri gerekmemelidir.

Düzenleme biletine bağlantı, meraklı bir geliştiricinin nasıl başarısız olduğunu bilmesini ve potansiyel olarak daha sonra tekrar ziyaret etmesini sağlar. Bu olmadan, oldukça statik hale gelebilir ve bir daha asla güncellenemez.

Kritik ve sezgisel olmayan bilgi parçaları, bilgileri dikkate alırken insanların bakacağı yerde belgelenmelidir.

Üzerinde çalıştığım ekipler ve projeler için, yeni sürümün neden başarısız olduğu hakkında yorum yaparak geri dönüş yapacağım. Yeni sürüm düzeltildiyse yükseltmeyi yeniden denemek için bir birikim hikayesi eklerdim. Kütüphanenin bağlandığı derleme sistemine / derleme komut dosyalarına yorumlar eklerdim.

Geri alma, gelecekteki geliştiricilere projenin geçmişine bakarken bağlam sağlayacaktır. Biriktirme hikayesi bu yükseltme ihtiyacını projenin aktif bir parçası olarak tutar. Derleme sistemi yorumları, kitaplığın sonunda güncellendiğinde değişikliklerin yapılması gereken yerlerdir.

Kodda yorum yapmam ve bir README'ye eklemem. Geliştirmeyi denemeyi düşünen geliştiriciler bu parçalara bakmayacak. Oraya eklerseniz, o zaman kütüphane ile ilgili sorun çözüldüğünde ve bir yükseltme yapıldığında, onu kaldırmanız gerekir. Bu adım çoğu zaman unutulur: Projeye karşı üretkenliği artıran notlar ortaya çıkar.

Projeniz farklı bir kurulum veya farklı bir akışa sahipse, cevabınız farklı olabilir. Anahtarın bilgiyi doğru koymak olduğunu düşünüyorum, yükseltme için çalışmaları yaparken geliştirici görecektir. Bu şekilde, yükseltme için zaman uygun değilse, geliştirici onu görecek ve duracak ve zaman doğru olduğunda geliştirici onu görecek ve notu kaldıracak, böylece gelecekteki geliştiricilerin kafasını karıştırmayacaktır.

Matthew'un yorumuna , önemli fikrini bir cevapta vurgulayarak daha fazla dikkat çekmek istedim . SDK'nızı yükseltmek istememenizin bir nedeni var ve bu sebep bir birim testinde ele alınmalı. Bir revizyon numarası için bir kontrol değil, temel sebep.

Örneğin, yeni sürümde bir hata olduğunu varsayalım. Bu hatayı kontrol eden bir birim testi yazın. Daha sonra bu hatayı SDK'da düzelttilerse, yükseltme sorunsuz bir şekilde gerçekleşir. Uyumsuz bir API değişikliği varsa, kodunuzun yeni API'yi veya SDK'nın eski API'yi desteklediğini kontrol eden bir test yazın. Bu, bir birim testinden daha çok bir entegrasyon testinden ibarettir, ancak yine de yapılabilir olmalıdır.

Şirketim günde 50+ komisyon üretiyor ve biz tam olarak büyük değiliz. Her geliştirici, her açık söz iletisini okumasa bile, ki yapmazlarsa dürüst olalım, kaydedilmiş bir taahhüt geçmişine ihtiyacımız olan tüm neden, insanların bunu hatırlayamamasıdır. Ve bir sorun çıkmazsa insanlar geri dönüp tarihi okumazlar. Ayrıca, henüz bilmedikleri kadarıyla bir yükseltme probleminden şüphelenmeleri için hiçbir nedenleri yoktur.

Elbette, işin kısa vadede tekrarlanmasını önlemek için bir e-posta gönderin ve derleme betiğinize ve bir README veya hata notuna not edin. Bununla birlikte, özellikle yeni sürümdeki sorun incelik ve sorun gidermek için zaman alıyorsa, bunu açıkça ortaya koymanın bir yoluna ihtiyacınız vardır. Bu bir birim testi anlamına gelir.

"Keşfedilen kritik bilgileri ekibin geri kalanına sadece taahhüt mesajı ile iletmeli miyim?" Çünkü bence hayır yapmamalısın, bunu açıkça belli ediyor. Çok fazla iletişim kurmaya çalışıyorum (bu, çoğu geliştirme ekibinin deneyimlerime göre aktif çaba göstermesi gereken bir şey) ve tuzaklar yaratmamak veya yalan söylemelerine izin vermemek için elimden geleni yapıyorum.

Beni böyle bir keşfe götüren eylemler zinciri bir bilet tarafından tetiklendiyse, bileti güncellerdim (ve bunu görmesi gereken kişilerin görünürlüğüne sahip olduğundan emin olun), muhtemelen yüz yüze söylerdim (umut ediyorum) en azından "Gee, Damon’ın bunu güncellemeyle ilgili bir şey söylediğini düşünüyorum" demişti.) ve elbette SDK’nın eklendiği noktadaki kodda hiç kimsenin güncellemediği bir yorumda bulunacağım. onu görme şansı olmadan. Şu anki takıma değil, gelecekteki işe alımlara daha fazla göz atmamıza rağmen, dev wiki'mizin bir yerinde bunu sıkıştırabilir miyim, görebiliyorum.

Sorununun karşılanması ve keşfedilmesi muhtemel zamana kıyasla sadece birkaç dakika daha sürer. Belgelerimizin en az kullanılan, düşük sinyalli parçalarından birinin kesinlikle buna karar vermesini istemedim.

Taahhüt tarihinde olmalı, ancak sadece taahhüt tarihinde olmamalı, bir an için yeni bir geliştirici kiraladığınızı hayal edin. Yeni geliştiricinizden, projenizin son 10 yılı için her bir taahhüt mesajını okumasını bekliyor musunuz, çünkü birkaçı kod tabanınızı anlamak için kritik öneme sahip olacak mı?

İkincisi, durumun değiştiğini ama kodun değişmediğini söyleyelim, “dokümantasyon” taahhütleri yapacaksınız, böylece “5432 revizyonundan mesaj atma artık yanlış, şu anki durum” satırları boyunca mesajlar ekleyebilirsiniz.

Bence takımın nasıl iletişim emin değilim ama en etkili Buna demek inanabiliyor ilk diyerek gövdeli "ACİL" olarak işaretlenmiş takımın eposta grubuna e-posta gönderip

Beyler, SDK v xyz kullanamıyoruz çünkü Foo ara belleğinin taşmasına neden oluyor ve Bar hizmeti çöküyor. Sürüm xyy ile sopa

Burada yaptığımız şey buydu ve mesajı oraya iletmenin en güvenilir yolu bu. Eğer varsa gerçekten telaşlı olmak istiyorum (ve e-posta sistemi izin verirse), e-posta üzerine bir "okuma makbuzu" istemek.

Tüm takıma bir kez bahsettikten sonra, daha ayrıntılı belgeler bir ekip wiki'sine konulmalıdır. Bu, belgelerinizi nasıl yapılandırdığınıza bağlı olarak değişecektir. Bağımlılık ve Gereksinimleriniz için özel olarak bir bölümünüz varsa, eklemek için iyi bir yer olurdu.

Bu tür bir sorunu belgelemek için ek bir yer, her zaman işe yaramasa da kaynak kodun kendisinde olabilir. Eğer SDK version ...sadece bir ya da iki açık yerlerde başvuruda bulunulan, yükseltmekte değil ilgili bir not içerebilir.

Kaynak denetimindeki dosya geçmişi çok uzun olabilir ve geliştiricilere bağlı olarak günde birkaç giriş olabilir. Bir hafta boyunca tatile çıkmış birinin bir haftanın kıymetli tarihini okumak için zamanı olmayabilir. README dosyası biraz daha merkezi olduğundan daha iyi bir yerdir ve insanlar onu okumaya daha meyilli olabilirler, ancak herkesin gerçekten README'yi okuyacağından emin olamazsınız . Sanırım değiştirildiğini görürlerse yapabilirler ...

Böyle bir şey, yorumlarda belirtilmiş olmalıydı, ancak başka yerlerde de olmasından fayda sağlayacak.

Yükseltme kararını kim verdiyse, gerçeklere sahip olması gerekir. Bu kişi kaynak kontrolünde yaşayamayabilir. Birisi bu problemi SO'da okumuş ve asla kodun temeline koymamış olsaydı?

Bu üçüncü taraf SDK ile ilgili bir tür belge olması gerekiyor.

• Hangi sorunu çözer?
• Bu özel neden seçildi?
• Sürümler, yükseltmeler, testler, vb. Kadar dikkate alınması gereken hususlar.
• Bu kararı kim veriyor?

Bunun gibi bir şeyin sürüm kontrolüne girmesine neden olan bir durum var ve bu bilgiyi mümkün olduğunca herkesin kullanmasını tavsiye etmelisiniz. Yalnızca ekibiniz, konuyla ilgili mümkün olduğunca fazla bilgi edinmek için herhangi bir belgede, kaynak kontrolünde veya hata izleyicide nerede arama yapılacağına karar verebilir. Aksi taktirde, unutacaksınız, yine de birileri yapacak ve birinin hafızasını tazeleyip tekrar hızlı bir şekilde geri alırsa şanslısınız.

Tarih, bilinçli bir şekilde onu arayan ve nerede olması gerektiğine dair genel bir algıya sahip olan bir okuyucuya yönelik verileri koymak için harika bir yerdir. Bir kullanıcı için aranması yerine, kullanıcılara sunulması gereken verileri koymak çok kötü bir yerdir.

Tarihler, nispeten sıralanmamış metnin çok büyük gövdeleridir. Genellikle bir geliştiriciye neyin değiştiği ve neyin değiştiği hakkında ayrıntılı bilgi sağlama amaçlıdır. Bu, ne aradıklarını bilmediği sürece bilgi yüklemesi olabilir.

Bir kullanıcı ne aradığını bilmiyorsa, bilgi yüzlerce işlem günlüğü altında hızlı bir şekilde gömülür ve önündeki bilgi yığınını budamak için hiçbir aracı yoktur.

Bu durumu iki temel problemin, muhtemelen üçünün olması olarak yorumluyorum.

• İstenmeyen bir SDK güncellemesi, ürünü olumsuz yönde etkileyebileceği bir kaynağa soktu.
• Sorudan: İstenmeyen yükseltmeyi gerçekleştiren katkıda bulunan, yükseltme yapmama konusunda önceki ve özel bir kararı bilmiyordu.

Bunlardan ilki bence en ciddi olanı. İstenmeyen bir SDK yükseltmesi koda girerse, başka sorunlar da olabilir.

Birisi yükseltme algıladığında başarısız olacak bir birim test durumu eklemeyi önerdi. Yükseltmenin gerçekleşmesini engellese de, bunun zamanla lav akışına yol açan tehlikeli bir yol olduğuna inanıyorum . Gelecekte bir noktada SDK'nın yükseltilmesi, yeni özellikler veya hataların giderilmesi veya eski sürüm artık desteklenmediği için kaçınılmaz görünüyor. Böyle bir ünite testi başarısız olduğunda ortaya çıkacak kafa çizilmeyi, hatta belki tartışmaları hayal edin.

Bence en genel çözüm geliştirme sürecini ayarlamak. Git için çekme isteği işlemini kullanın . Subversion ve daha eski araçlar için branş ve fark kullanın. Ama sahip bazı üst düzey geliştiriciler bu tür konuları yakalamak için izin verir işlemi öncesinde onlar kod temeli haline getirerek ve diğer geliştiriciler etkiler.

Çekme talebi işlemi sizin durumunuzda kullanılsaydı ve her çekme talebi dar ve spesifik olursa, fazla zaman harcanmazdı. SDK’yı yükseltmek için bir çekme isteği gönderilmiş ve yükseltme isteminin istenmediği yorumuyla reddedilmiştir. Başka hiç kimse etkilenmeyecekti ve şimdi de SDK yükseltmesini geri döndürmeye gerek kalmayacaktı.

Ancak asıl soruya doğrudan cevap vermek için, diğer geliştiricilerin, tüm geliştiricilerin, kodun tüm revizyon geçmişini tam olarak okumasını, bunun gibi bildirimlerin değerli bir zaman kaybı olduğunu umarak kabul ediyorum. Kısa ekip e-postasında yanlış olan ne?

Olası üçüncü konu: Güncelleme neden ilk sırada istenmiyor? Açıkça en az bir geliştirici, yükseltme işleminin iyi bir şey olacağını düşündü. Yükseltmeyi geciktirmek için birçok iyi neden vardır, fakat aynı zamanda birçok kötü olanı da vardır. Lav akışını (gereksiz yere geriye dönük uyumluluk kodu) ve kargo kültünden ("bunu yükseltemeyiz ama nedenini bilmiyorum") anti-kalıpları önlemeye özen gösterin !

Bu tür bir bilgiyi bir taahhüt geçmişine eklemenin sorun değil, ancak doğru şekilde belgelendirilmesi gerektiğini söyleyebilirim. Geçenlerde birleşme (atlasiyen tarafından) kullanmaya başladık. Aranabilir, belirli sayfaları sık kullanılanlar vb. Olarak ayarlayabilirsiniz.

Diğer bazı araçlar evernote veya google docs’da halka açık bir defter olabilir.

Karl'ın cevabını genişleterek , kontrol sürecinin bir parçası olarak kısıtlamayı otomatik olarak uygulayan bir yaklaşımla giderdim. Bir doc / wiki / README okumak gibi geliştirici adına proaktif bir işlem gerektirmeyen ve gizlice geçersiz kılınamayan bir şeye ihtiyacınız vardır.

TFS kaynak kontrol alanında , check-in sırasında kurallar uygulayan özel check-in politikalarını kodlayabilirsiniz . Örneğin, bekleyen bir check-in işlemine sahip olan bir yapılandırma dosyasındaki sürümü değerlendiren ve xyz'ye eşit değilse, başarısız olacak bir politika tanımlayabilirsiniz. Politikalar geçersiz kılınabilir, ancak bu olduğunda uyarı vermek mümkündür.

Karl'ın da belirttiği gibi, SDK versiyonunu doğrudan veya dolaylı olarak değerlendiren bir tür birim testiyle başarısız olacak bir alternatif-geçitli girişler olabilir.

Bu cevabın çok TFS merkezli olduğunu, ancak durumunuzda geçerli olan sürüm kontrolü / CI sistemlerinde (TFS değilse) muhtemelen benzer özelliklerin bulunduğunu takdir ediyorum.