मेरा पसंदीदा Git commit (2019)

 (dhwthompson.com)
3 पॉइंट द्वारा GN⁺ 2024-02-02 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • GOV.UK पर काम के दौरान Dan Carley का “Convert template to US-ASCII to fix error” commit दिखाता है कि छोटा code change भी विस्तृत commit message के जरिए codebase का दीर्घकालिक documentation बन सकता है
  • अच्छा message यह दर्ज करता है कि क्या बदला, उससे ज्यादा यह कि क्यों बदला; इस उदाहरण में bundle exec rake चलाने पर आए invalid byte sequence in US-ASCII error और उसे reproduce करने की शर्तों को विस्तार से रिकॉर्ड किया गया है
  • error string और जांच की प्रक्रिया साथ में दर्ज होने से, बाद में वही समस्या मिलने पर कोई व्यक्ति git log --grep या GitHub commit search से पुराना समाधान रिकॉर्ड खोज सकता है
  • message में find -exec, file --mime, iconv जैसे Unix tools के इस्तेमाल की प्रक्रिया भी शामिल है, जिससे reviewer और बाद के reader समस्या सुलझाने का flow follow कर सकते हैं
  • हर commit इतना लंबा होना जरूरी नहीं, लेकिन context, जांच की प्रक्रिया और भावनाएं तक दर्ज करने वाला message टीम की codebase की साझा समझ और भरोसा बनाने में मदद करता है

छोटे बदलाव को दीर्घकालिक documentation बनाने वाला commit

  • Git commit message, अगर अच्छी तरह लिखा जाए, तो codebase के पूरे जीवनकाल तक टिकने वाला मजबूत documentation tool बन सकता है
  • उदाहरण के तौर पर लिया गया commit Government Digital Service में GOV.UK पर काम करने के समय का बदलाव है
  • लेखक Dan Carley हैं, और title है “Convert template to US-ASCII to fix error”
  • GDS के खुले development तरीके की वजह से ऐसे internal संगठनात्मक उदाहरण भी बाहर साझा किए जा सकते हैं

लंबाई से ज्यादा जरूरी context

  • इस commit में code change की मात्रा की तुलना में message लंबा है, लेकिन इसकी मुख्य value लंबाई में नहीं बल्कि उपयोगी context में है
  • यही बदलाव कहीं और change whitespace, fix bug की तरह छोटा लिखा गया हो सकता था
  • Dan ने आसपास के colleagues और बाद के readers को समस्या की वजह और समाधान की प्रक्रिया समझाने के लिए detailed record छोड़ा

क्या बदला से ज्यादा, क्यों बदला

  • अच्छा commit message सिर्फ बदली हुई चीजों को नहीं, बल्कि क्यों बदला गया यह भी समझाता है
  • यह commit दर्ज करता है कि feature branch में /etc/nginx/router_routes.conf के content से match करने वाला test जोड़ने के बाद, चलाने के तरीके के हिसाब से result अलग था
    • bundle exec rake spec या bundle exec rspec modules/router/spec से चलाने पर सब ठीक चलता था
    • bundle exec rake से चलाने पर हर should block fail होता था
    • error था ArgumentError: invalid byte sequence in US-ASCII
  • ऐसी explanation न होती तो किस tool में किस तरह का parsing error आया, इसका अंदाजा लगाना पड़ सकता था
  • मूल काम का context लोग भूल सकते हैं, team बदल सकते हैं, या organization छोड़ने पर आसानी से गायब हो सकता है

खोजा जा सकने वाला error record

  • commit message की शुरुआत में बदलाव की वजह बना error message जस का तस मौजूद है
  • वही error मिलने पर कोई व्यक्ति codebase में पुराने record को इन तरीकों से खोज सकता है
  • search results में दिखा कि कई लोगों ने इस error को खोजा था, और यह भी पता चल सका कि पहले किसने समस्या का सामना किया और क्या action लिया

समस्या सुलझाने की प्रक्रिया को कहानी की तरह दर्ज करना

  • message इस तरह structured है कि समस्या कैसे दिखी, किस क्रम में जांच की गई, और आखिरकार कैसे ठीक की गई—यह follow किया जा सके
  • उदाहरण के लिए इसमें शामिल है कि .with_content(//) matcher हटाने पर error गायब हो गया, spec file में कोई अजीब character नहीं था, और उसी interpreter में Puppet को require करने पर इसे reproduce किया जा सकता था
  • commit message किसी खास file, function या code की एक line को नहीं, बल्कि बदलाव को ही document करता है, इसलिए codebase ने जो यात्रा तय की है उसे record करने के लिए यह अच्छी जगह है

टीम के ज्ञान को बढ़ाने वाला side effect

  • Dan ने जांच के हर step में चलाए गए commands record किए, और यह टीम के भीतर knowledge को हल्के-फुल्के तरीके से फैलाने का तरीका बन सकता है
  • reader सिर्फ commit message से भी Unix tools का इस्तेमाल सीख सकता है
    • find में -exec argument देकर मिली हर file पर command चला सकते हैं
    • command के अंत में \+ लगाने से हर file पर अलग-अलग चलाने के बजाय कई filenames को एक ही file command में pass किया जाता है
    • file --mime file का MIME type बताता है
    • iconv नाम का tool मौजूद है
  • बदलाव review करने वाले व्यक्ति के साथ-साथ बाद में इस commit को खोजने वाले व्यक्ति को भी वही जानकारी मिलती है
  • पर्याप्त समय और commits जमा होने पर ऐसे messages टीम के लिए knowledge amplification device बन सकते हैं

सहानुभूति और भरोसा बनाने वाला record

  • commit के अंत में “Now the tests work! One hour of my life I won't get back..” वाक्य है
  • यह वाक्य एक घंटे तक चतुर bug को track करने वाले developer की झुंझलाहट और उसे सुलझाने की संतुष्टि बताता है
  • short-term hacking या prototype code के production में जाकर जड़ें जमा लेने के मामलों में भी, ऐसे messages याद दिलाते हैं कि हर बदलाव के पीछे उस समय उपलब्ध जानकारी में सबसे अच्छा decision लेने वाला कोई व्यक्ति था

हर commit का लंबा होना जरूरी नहीं

  • यह उदाहरण extreme है, और खासकर इस आकार के हर commit से इसी level की detail की उम्मीद करने की जरूरत नहीं
  • फिर भी यह बदलाव के पीछे का context समझाने, दूसरों को सीखने देने, और टीम के codebase के बारे में shared mental model में योगदान देने का अच्छा उदाहरण है
  • अच्छे commit messages और changes को structure करने वाले tools में रुचि हो तो ये resources देखे जा सकते हैं

संबंधित पढ़ाई

1 टिप्पणियां

 
GN⁺ 2024-02-02
Hacker News की राय

  • अच्छा हो या बुरा, GitHub के co-founder और Pro Git जैसी Git किताब लिखने वाले व्यक्ति के नज़रिए से, Git commit messages code documentation का एक अनोखा रास्ता हैं, लेकिन बेहद अप्रभावी हैं
    मुख्य समस्या यह है कि Git, GitHub वगैरह ज़्यादातर tools आम तौर पर सिर्फ पहली लाइन दिखाते हैं। उदाहरण वाला commit भी “US-ASCII error” जैसी सामान्य एक लाइन ही दिखाता है, और लेख में जिस बाकी सामग्री की तारीफ़ की गई है उसे आधुनिक tools में लगभग कोई नहीं देखता
    Git ने commit messages को project के सभी लोगों द्वारा पढ़े जाने वाले email body के रूप में design किया था, लेकिन आजकल वे अधिकतर वह भूमिका नहीं निभाते। जब तक mailing list पर patch series के रूप में चर्चा न हो, title के पहले 50 characters के अलावा लगभग कुछ नहीं पढ़ा जाता
    git blame में -w -C -C -C है या दो -C हैं, यह ढूंढकर संबंधित message trace करने पर भी सिर्फ पहली लाइन दिखती है, और आखिर में लंबे message को देखने के लिए SHA ढूंढकर git show करना पड़ता है। अच्छी तरह लिखे जाने पर भी information को फिर से ढूंढना बहुत मुश्किल है—Git को लेकर मेरी सबसे बड़ी शिकायतों में से एक यही है
    Git project का इतिहास देखें तो commit messages लगभग हर बार शानदार होते हैं, लेकिन किसी एक file पर blame चलाने पर भी function implementation का context follow करना बहुत मुश्किल है। Jeff King ने पिछले 10 सालों में जो documentation छोड़ी है वह genius level की है, लेकिन भयावह बात यह है कि लगभग कोई उसका आनंद नहीं ले पाता
    सही समाधान क्या है, नहीं पता, लेकिन ज़्यादातर communities में commit messages के रूप में बेहतरीन documentation लिखना दुखद रूप से लगभग समय की बर्बादी जैसा है। क्योंकि उसे ढूंढना बहुत मुश्किल है

    • GitHub के आने से पहले से Git में योगदान देने और legacy code maintain करने वाले व्यक्ति के रूप में मैं इससे बिल्कुल सहमत नहीं हो सकता। terminal में git blame, git log, git show हमेशा इस्तेमाल करता हूं, file history follow करना आसान है और git log -G से add/delete होने का समय ढूंढने में कुछ सेकंड ही काफी होते हैं
      मुश्किल तब होती है जब commit तो मिल जाता है, लेकिन message बस “bleh” या “add a thing” होता है। developer ने सिर्फ 60 सेकंड लगाकर यह लिख दिया होता कि ऐसा क्यों किया, तो बात बन जाती
      इसके उलट, जब किसी बदलाव के क्यों किए जाने की विस्तार से व्याख्या करता commit message मिलता है तो सच में खुशी होती है। एक अच्छा commit message घंटों, दिनों का काम बचा देता है
      GitHub भी खराब commit messages की समस्या में योगदान देता है। किस्मत अच्छी हो तो PR description में details मिल जाती हैं, लेकिन वह commit log के ठीक बगल में नहीं होती; और अधिकतर PR Jira link पर, Jira Slack conversation link पर, और Slack Google Docs link पर ले जाता है
      industry documentation में वाकई खराब है, लेकिन Jeff King जैसे लोग सही लड़ाई लड़ रहे हैं। आखिरकार मुझे लगता है कि यह technical समस्या नहीं, लोगों की समस्या है। documentation लिखने का तुरंत reward नहीं मिलता, इसलिए यह extra काम जैसा लगता है, और reward कई दिन, कई हफ्ते या कई महीने बाद ही दिखता है
      कृपया अच्छे commit messages लिखें। सिर्फ 1 मिनट लगाकर यह लिख दें कि क्यों किया, तो हर commit कोई कमबख्त Chesterton’s fence puzzle नहीं बनता। उसे आसानी से मिल सकने वाले commit message में रख देंगे तो आपका भविष्य वाला खुद और मैं आपका शुक्रिया अदा करेंगे
      साथ ही, मैं इस दावे से भी सहमत नहीं हूं कि commit messages ढूंढना मुश्किल है। code की किसी line, function, file का इतिहास follow करने में मुझे लगभग कोई दिक्कत नहीं होती, और commit message दोबारा न भी पढ़ा जाए तो भी लिखते समय उसका मूल्य होता है। अच्छा message लिखने से मैं verify करता हूं कि मैंने सच में वही code लिखा है जो मेरा इरादा था, और code reviewer के लिए भी यह valuable है
    • “Git ने commit messages को project के सभी लोगों द्वारा पढ़े जाने वाले email body के रूप में design किया था” यह बात मानना मुश्किल है। असल में यह इस बात के ज़्यादा करीब है कि commit subject या बदली हुई files में रुचि रखने वाला व्यक्ति body पढ़ता है; मुझे समझ नहीं आता कि दूसरे लोगों को immutable historical document क्यों पढ़ना चाहिए
      git blame options ढूंढना मुश्किल है, यह बात भी मज़ाक जैसी लगती है। अच्छा IDE हर line पर blame info लगाता है, एक button से diff दिखाता है, और उस diff में context lines या deleted lines पर recursively blame कर पाने देना चाहिए। Tig जैसे tools ठीक यही करते हैं
      यह मानता हूं कि GitHub commit messages देखना मुश्किल बना देता है
      commit से जुड़ी documentation मज़े के लिए नहीं लिखी जाती। यह बाद में शायद मौजूद न रहने वाले व्यक्ति द्वारा भेजे patch को accept करने का risk घटाती है, और संबंधित सोच को उजागर करती है ताकि दूसरे लोग उस पर काम कर सकें। सोच छिपाने से code पर exclusive ownership जमा होती है, और आम तौर पर यह अच्छी बात नहीं होती। commit messages proof of work की भूमिका भी निभाते हैं, और patches बहुत ज़्यादा होने पर महत्वपूर्ण हो सकते हैं। commercial projects में इसका कुछ महत्व कम हो सकता है
    • terminal Git में मैं बहुत अच्छा नहीं हूं, लेकिन IntelliJ या Emacs का Magit इस्तेमाल करने पर किसी file को बदलने वाले सभी commits आसानी से मिल जाते हैं, और पूरा commit message भी आराम से browse किया जा सकता है। सही tools इस्तेमाल करें तो यह मुश्किल नहीं है, और लगता है लगभग सभी के पास इसी तरह के tools हैं। क्या सच में लोग Git CLI से ही चिपके रहकर सैकड़ों commands और flags याद करना चाहते हैं? समझ नहीं आता क्यों
    • यह GitHub वगैरह की failure है। शायद GitHub मानता है कि users commit history से inference नहीं कर सकते, इसलिए वह simplify करने की कोशिश करता है, और उसका एक परिणाम यह है। खासकर private GitHub repositories की अव्यवस्था कभी-कभी यकीन से परे होती है
      ऐसी documentation रखने की जगह सच में कहीं और नहीं है। code comments में यह फिट नहीं बैठती। लेकिन अब developers की ऐसी generation बन गई है जो सोचती है कि Git ही GitHub है, और Git का एकमात्र उद्देश्य changes को GitHub पर upload करना है
      Git अच्छा नहीं है, लेकिन बाकी चीज़ों से बहुत कम खराब है। हमें मूल बातों पर लौटकर version control का वास्तविक उद्देश्य समझना चाहिए
    • फिर भी historical research के लिए यह शानदार है। यह उन गिनी-चुनी documentations में से है जो code के साथ हमेशा बची रहती हैं। GitHub या अन्य centralized रूप कोई ऐसा open data format नहीं हैं जिसे लोग आसानी से backup, convert या migrate करें; इसलिए project move करने पर आम तौर पर data पीछे छूट जाता है
      इसलिए हो सकता है कि यह मौजूदा community के लिए बहुत मददगार न हो, लेकिन कुछ साल बाद debugging करने वाले व्यक्ति के काम आता है

  • कुल मिलाकर मंशा से सहमत हूं, लेकिन बेहतर होगा कि शुरुआत में और ज़्यादा ठोस BLUF रखा जाए। जैसे “Fix test issues caused by non-breaking space character \xa0” लिखना
    इससे तुरंत समझ आ जाता है कि समस्या क्या है, और अगर कोई और जानना चाहे तो नीचे पढ़ने की आज़ादी भी रहती है

    • मुझे लगता है यह मैसेज कहीं बेहतर है। GitHub में diff देखने पर यह भी काफ़ी साफ़ दिखता है कि क्या बदला है। अगर diff बिल्कुल वैसा ही दिखने वाला change set हो, तो मामला बस किसी अदृश्य character के जुड़ने या हटने का ही हो सकता है
      इसलिए रिकॉर्ड में खोजने के लिए एक अच्छी पहली लाइन वाला मैसेज ही काफ़ी है। बग की जड़ तक पहुंचने के लिए नर्निया तक जाकर लौटने की छोटी कहानी ज़्यादा प्रासंगिक नहीं लगती। हां, PR description या commit के extended message में भड़ास निकालने के तौर पर लिखने से मुझे एतराज़ नहीं
    • आदर्श commit message भी लगभग इतना ही होना चाहिए। लेख में बाकी body तो बस यह कहानी है कि इसे कैसे खोजा गया। काम की प्रक्रिया समझाने वाली बातें Git commit message में डालने की ज़रूरत नहीं लगती। वह message बताता है कि क्यों और कौन-सा बदलाव किया गया, और इतना काफ़ी है
    • यह concept पसंद आया। हमेशा सबसे ऊपर सबसे actionable या महत्वपूर्ण बात रखें, और उसके बाद context दें। दूसरों के समय का सम्मान करना चाहिए और मुख्य बात को दबाकर नहीं रखना चाहिए

  • बेहतरीन commit message लिखने का गर्व मैंने महसूस किया है, लेकिन दूसरों को उससे मिलने वाली value को लेकर उतना आश्वस्त नहीं हूं। जब कोई अजीब error message मिलता है, या नया feature जोड़ना होता है, या लगभग किसी भी स्थिति में, मुझे लगता है कि ज़्यादातर लोग commit messages में search नहीं करते
    थोड़ा दुख की बात है, लेकिन मुझे यह शक बढ़ता जा रहा है कि खूबसूरत commit messages में programmer की vanity जैसा पहलू काफ़ी होता है। उनकी तारीफ़ ज़्यादातर खुद लेखक ही करता है, और बाकी लोग बिना नोटिस किए आगे बढ़ जाते हैं
    कभी-कभी ऐसी aesthetic सजावट की जगह हो सकती है, लेकिन मुझे यक़ीन नहीं कि उसकी practical value बहुत बड़ी है। अब अगर कोई और “fix whitespace issue” commit करे तो मैं ज़्यादा परेशान नहीं होता, और शायद इससे मैं बेहतर colleague बन गया हूं
    Git या Linux जैसे projects में बात अलग हो सकती है, जहां बहुत बड़ी distributed team और अनगिनत commits होते हैं। जिन projects से मैं परिचित हूं, उनमें contributors 1 से 100 के बीच होते हैं और ज़्यादातर एक ही organization से होते हैं

    • commit message की value तब भी होती है जब उसे पूरी ज़िंदगी सिर्फ़ आप ही पढ़ने वाले हों। किसी समस्या को binary search करते समय आखिर में मिले commit का message वाकई उपयोगी होता है। अगर वह सिर्फ़ “fixed thing” न होता तो और भी उपयोगी होता। इसका मतलब यह भी है कि वैसी ही समस्या फिर मिलने पर आपके पास खोजने लायक commit notes होंगे
    • अजीब लग सकता है, लेकिन जिस project में मैं सक्रिय रूप से शामिल हूं, उसमें हर commit को कम-से-कम सरसरी तौर पर देखने की कोशिश करता हूं। अगर open source project है, तो वह commit message हमेशा रहेगा, और सिर्फ़ code search ही नहीं बल्कि सामान्य search engines में भी index हो सकता है। हालांकि GitHub अब bots को जिस तरह और रोक रहा है, शायद यह कम सच हो
      जब Google या Stack Overflow से जवाब नहीं मिलता, तो GitHub पर भी देखता हूं कि मिलता-जुलता कुछ PR या commit message में है या नहीं। जिन private repositories तक मेरी पहुंच है, उन्हें मिलाकर मुझे अनगिनत बार मदद मिली है। अच्छे commit messages vanity से आगे जाकर निश्चित रूप से valuable होते हैं। अगर बहुत से developers उन्हें नहीं देखते, तो यह उनका नुकसान है, और उम्मीद है अनुभव बढ़ने पर वे कभी समझेंगे। junior developer को search करना सिखाना या उन्हें मूल लेख भेजना भी अच्छा है
    • बहुत छोटे commit messages से मैं कई बार ठगा गया हूं। कोई पूछता है “ऐसा क्यों किया?”, तो मैं Git history देखता हूं, और 3 साल पहले खुद छोड़ा हुआ “it should be done this way” message मिल जाता है
      उसके बाद से मैं कोशिश करता हूं कि commit message कम-से-कम भविष्य वाले मुझे यह याद दिला सके कि बदलाव की ज़रूरत क्यों पड़ी थी
    • code की एक line बदलने से पहले अगर आप git blame नहीं करते, तो आप गलत कर रहे हैं
      कई बार ऐसा हुआ है कि किसी साफ़ bug को ठीक करने जा रहा था, लेकिन commit से ठीक पहले पिछले commit को देखा तो पता चला कि वह “bug” जानबूझकर डाला गया था, और linked JIRA task में अच्छी तरह समझाया गया था कि मेरा साफ़-साफ़ लगने वाला बदलाव 2 साल पुराना bug फिर से क्यों बना देगा
    • IDE के git blame feature से मैं अक्सर समझता हूं कि क्या हुआ था। अच्छा commit message मिल जाए तो आभार महसूस होता है

  • commit message की पहली line सबसे महत्वपूर्ण है, क्योंकि वह git log को Chesterton’s fence से निपटने लायक बनाती है। इस मामले में लेखक ने निशाना चूक दिया लगता है
    पहली line में क्या किया गया, नहीं बल्कि क्यों किया गया, यह डालना मुख्य बात है। क्या बदला है, यह जानने में रुचि रखने वाला व्यक्ति code या diff देख सकता है
    उदाहरण के लिए “nginx .conf files must be in us-ascii” लिखें, फिर “changed blahblah.erb to remove nonbreaking space character” रखें, और उसके बाद बाकी काफ़ी अच्छा commit message जारी रखें
    इसे news article की तरह सोचना चाहिए। मानकर चलें कि reader किसी भी point पर पढ़ना बंद कर सकता है, और लिखना ऐसे चाहिए कि महत्व घटता जाए और details बढ़ती जाएं

    • पहली line में पहले तो क्या बदला है उसका summary होना चाहिए, ताकि problematic commit मिल सके
      news article भी title में why नहीं, what बताता है
      इस मामले में original की पहली line बिल्कुल सही है। git log देखते हुए आप मान सकते हैं कि इस commit ने tests के functional behavior को शायद नहीं बदला, और आगे बढ़ सकते हैं
    • किसी arbitrary project का commit message किसी को nginx rules सिखाने की जगह नहीं है
      “nginx .conf files must be in us-ascii” bug या PR title के लिए अच्छा हो सकता है, लेकिन कई commits अलग-अलग कामों से जुड़े हो सकते हैं, और असल में क्या हुआ यह नहीं बताता। फाइलों को US-ASCII में convert किया जा रहा है, कोई conversion tool बनाया जा रहा है, documentation update हो रही है, tests बनाए जा रहे हैं, या इनमें से कोई combination है—यह पता नहीं चलता। why के बजाय what से शुरू करने पर यह confusion कम होता है
    • मुख्य बात बस इतनी कहनी चाहिए कि चूंकि कभी-कभी सिर्फ़ पहली line output होती है, इसलिए पहली line में ऐसी बात रखें जो अपने-आप में अर्थपूर्ण हो
      “The files must be in us-ascii” हो या “Changed the files to us-ascii”, इससे बहुत फ़र्क नहीं पड़ता। दोनों साफ़ बताते हैं कि files US-ASCII में बदली गई हैं

  • इस तरह की documentation approach की कमी यह है कि एक बार लिखा गया commit message असल में बदला नहीं जा सकता
    बेशक rebase से यह संभव है, लेकिन जो चीज़ 1 साल पहले लिखी गई थी और पहले ही main में merge हो चुकी है, क्या उसे सचमुच बदलकर सबकी feature branches को दर्द देना चाहेंगे
    .md file, Wiki, Confluence में रखे docs से तुलना करें तो, मैं किसी colleague की लिखी चीज़ बेहतर कर सकता हूँ, और दूसरा colleague मेरी लिखी चीज़ बेहतर कर सकता है
    इस मामले में bug ठीक हो गया है और शायद दोबारा न आए. लेकिन किसी खास component को commit करते समय उसकी design समझाने का temptation होता है, और अब मैं उससे बचता हूँ. business requirements बदलने आदि से अगर बाद में वह component बदल जाए तो क्या होगा. क्या commit docs सिर्फ diff ही समझाएँगे. तब नए team member को system समझने के लिए कई commit messages पढ़कर दिमाग में merge करने होंगे

    • वह कमी नहीं है. commit एक historical record है, इसलिए 3 साल बाद लौटने पर मैं जानना चाहूँगा कि उस समय के context में उसका purpose क्या था, कोई धुली-पुंछी history नहीं देखना चाहूँगा
      .md file या Wiki, Confluence से तुलना करना bicycle और goose की तुलना करने जैसा है
      component बनाते समय की considerations या trade-offs, या यह तथ्य कि वे थे ही नहीं, अक्सर original defect, बाद के evolution और use case changes से पैदा defects को समझने में उपयोगी होते हैं
      नए team member को system समझना हो तो अलग से “current” document maintain किया जा सकता है. उस document को implementation trade-offs या यह बात कि draft time pressure में लिखा गया था, सब cover करने की जरूरत नहीं
    • मुझे लगता है कि commit message का edit न हो पाना उल्टा एक advantage है. बाद में सुधार करना मुश्किल है, लेकिन codebase की history को step by step follow करना सचमुच बहुत कुछ उजागर करता है
    • commit message कोई ऐसा document नहीं है जिसे समय के साथ update होना चाहिए, बल्कि एक single change का historical record है. बाद में यह एहसास होना कि कोई जरूरी detail छूट गई, अफसोस की बात है, लेकिन कुल मिलाकर उसका कभी न बदलना महत्वपूर्ण है
    • मुझे लगता है Git की गलती यह थी कि उसने क्या बदला इसका immutable log और क्या merge हुआ इसकी ideally mutable कहानी, दोनों को मिला दिया. इसलिए commit squash, rebase, merge को लेकर बहस होती है
      commits squash करने से feature addition की कहानी के रूप में record बेहतर हो जाता है, merge वास्तविक code changes का immutable log बचाए रखता है, और rebase दोनों थोड़ा-थोड़ा करता है
      दोनों न रख पाने की कोई वजह नहीं है. हम computer program करने वाले लोग हैं, इसलिए जैसा चाहें वैसा बना सकते हैं
      अगर मैं Git को नए सिरे से लिखता, तो commit को दो हिस्सों में बाँटता. change history को Git की तरह Merkle DAG जैसी structure में immutable रखता, और commit messages को अलग associated data store में रखकर workflow समझाने वाला reasonable और editable log बनाता. feature tags के basis पर commits को group करने, typos ठीक करने, messages मनचाहे तरीके से बदलने देता, लेकिन नीचे का diff log, यानी “code में सच में क्या बदला”, वैसा ही preserve रहता
    • git notes से add किया जा सकता है. हालांकि message अगर इतना लंबा हो तो किसी के notice करने की संभावना कम लगती है

  • एक बात से सहमत नहीं हूँ. वह हिस्सा कि “हर commit, खासकर इस size के commit, में इस level की detail की उम्मीद नहीं करता”
    मेरे अनुभव में उल्टा, छोटी और harmless दिखने वाली चीज़ों को अक्सर relatively लंबी explanation चाहिए होती है
    कल मैंने gh pr list में --limit=999 जोड़ने की वजह तीन paragraphs में लिखी. क्योंकि यह confusing है. --jq argument के अंदर पहले से limit( है, और अगर मान लें कि total PRs infinite हैं, तो value जितनी ज्यादा होगी, final result असल में उतना कम होगा
    मैंने code comment भी लिखा, और शायद लिखने से ज्यादा समय सोचने और refine करने में लगाया होगा. जब कोई इशारा करे कि यह काम बस अंधाधुंध code लिखना है, तो अगला example यही याद रहे

    • मैं सहमत हूँ कि छोटी और harmless दिखने वाली चीज़ों को लंबी explanation चाहिए हो सकती है, लेकिन linked commit message बहुत लंबा लगता है. यह reader का समय बर्बाद करता है, या text wall की वजह से आँखें धुंधला देता है. आपने क्या पाया और क्यों, यह document करने के लिए पूरी journey record करना जरूरी नहीं
      “This was a non-ascii whitespace character that caused ArgumentError: invalid byte sequence in US-ASCII when running bundle exec rake” इतना काफी है. बाद में similar problem खोजने के keywords हैं, root cause मौजूद है, और यह इतना लंबा भी नहीं कि लोग skip कर दें
    • अगर commit language binding add करने का है, तो additions/deletions 100 lines से ऊपर हों तब भी “Add X function” जैसा लिखना काफी हो सकता है. क्योंकि वह बस already established pattern follow कर रहा है. लेकिन linked type के change के लिए कई paragraphs की explanation निश्चित रूप से उपयोगी है
    • code comments भी similar pattern में लिखे जाते हैं. “interesting” code के छोटे core हिस्से में comment-to-code ratio 1:1 या उससे ज्यादा हो जाता है, और इसी की बदौलत बाकी codebase boring और self-explanatory boilerplate code बना रह सकता है, जिसे ज्यादा comments की जरूरत नहीं पड़ती

  • मुझे नहीं लगता यह शानदार Git commit है
    इतने text के मुकाबले first line “Convert template to US-ASCII to fix error” बेहतर हो सकती थी. कौन सा whitespace character error कर रहा था और error क्या था, बस कुछ शब्द और जोड़ने की जरूरत थी. वह explanation और diff मिलकर जरूरी context के लिए काफी हैं
    ईमानदारी से कहूँ तो बाकी लगभग बेकार है. नुकसान नहीं करता, लेकिन value भी ज्यादा नहीं. author ने इस bug को track करने की अपनी journey document की है, लेकिन कौन परवाह करेगा

    • जो लोग सीखना और बेहतर programmer बनना चाहते हैं, वे परवाह करेंगे. दरअसल article उस extra content की value समझाता है, और इसका मतलब है कि कुछ लोग परवाह करते हैं
      article में उन लोगों के कई commits दिखाने वाला search result link भी है जिन्होंने उस fix से सीखा
      वह commit message knowledge का खजाना है

  • अच्छे commit messages देखने हों तो Linux kernel की Git history देखें. वहाँ यह standard है
    पहली line हमेशा change से प्रभावित subsystem का ज़िक्र करती है, फिर imperative one-line summary होती है. उसके बाद तीन सवालों के जवाब जितना हो सके detail में दिए जाते हैं

    1. current behavior क्या है
    2. किस चीज़ ने इस change तक पहुँचाया
    3. change लागू होने के बाद नया behavior क्या है
      Example इस तरह लिखा जा सकता है: “current code X करता है. test case T चलाने पर unexpected behavior U observe हुआ. यह reason R की वजह से है. F करके fix करते हैं”

  • हाल ही में एक contributor ने मेरे Git message approach के बारे में कहा कि मेरी requirements “अनोखी” हैं। शायद Linux kernel background झलक गया होगा, लेकिन मेरे सभी commit messages यहां दिखाए गए जैसे ही होते हैं
    अगर बात मौजूदा code के बारे में है, तो comments code के साथ होने चाहिए। process से जुड़ी बातें, जैसे हटाया गया code या वह code जो काम नहीं कर रहा था, commit में होनी चाहिए
    सबसे अहम बात यह है कि commit message सुविधा के लिए issue को refer कर सकता है, लेकिन मुख्य details को ज़रूर दोहराना चाहिए। GitHub अस्थायी है, लेकिन Git messages नहीं

  • context से भरे commit messages यहां हैं[1]
    यह इतनी आम बात है कि maintainer ने यह लेख लिखा[2]
    [1] https://github.com/git/git/commit/d70f554cdf38b0b05cfaa8e8eb...
    [2] https://lore.kernel.org/git/xmqqedevo8ps.fsf@gitster.g/