在前一回中我提到了,究竟應該將那些類型的檔案,納入版本控制系統的管理範圍,以及進行提交動作的前置條件。簡單來說,提交的頻率愈高愈好,但是,所提交的內容必須是可以正常建構(例如通過編譯),而且最理想的情況就是,每次所提交的內容,恰好是一個不可分割(atomic)的工作,例如一個小功能的增加,或是一個臭蟲的修正。這使得我們在版本間追溯時,其粒度不致於太小,也不會太大。

關於提交,還有一個重要的議題我們沒有提到,那就是關於提交時的記錄訊息。每當我們在版本控制系統上要進行提交動作時,系統會允許我們填入提交記錄訊息(Commit Log),以便記錄和這次提交內容相關的資訊。有些系統甚至強迫你必須填寫,不能省略,這是因為,提交訊息對於版本管理來說相當重要,少了提交的記錄訊息,就不能理解每個版本變遷之間,究竟發生了什麼變化、為什麼要發生變化。而這麼一來,也就缺少了版本演化過程的提交歷史(Commit History)。對開發者來說,版本控制系統的作用,就幾乎只剩下做為集體共用、自動整合彼此修改內容的檔案庫了。

提交訊息的目的
事實上,追溯到開發歷程中的任一個版本,也是版本控制系統的重要作用之一。我們並不會總是只使用最新的版本,有時最新的版本即使添加了新功能或是修正了臭蟲,但是新加入的功能或臭蟲的修正,都有可能引入不穩定的程式碼或是產生副作用。為了和不穩定的版本進行比較,以找出不穩定或造成錯誤的根源,就必須找出自前一次穩定版本,至最新版本間的所有變化歷史。有時候,基於一些其他的目的,我們也會想要倒回到任一個版本。例如,使用某一個出貨版本的使用者反映在該版本上的問題,為了驗證使用者所反映的問題,也為了要基於該版本來做修正,你就必須要能夠從版本控制系統中取出該版本。

當然,少了版本控制系統的協助,你也可以在每次出貨時,將該出貨版本的所有原始碼及檔案,全部都製作一份複本。之後,若發現該版本上的任何問題,便可基於該複本,做問題的查驗,以及問題的排除。但是這麼一來,一來沒有辦法查看每個出貨版本中間的修改歷程,了解該版本和之前版本的差異;二來,在對問題進行修改之後,所做的修改部份,也不易繼續利用版本控制系統,將變動套用到該版本之後的所有版本中(如果打算套用。我們會等到講版本的「分支」以及「合併」時再來討論這個議題)。因此,完全透過版本控制系統來進行管理,才會是比較合適的方式。

也因為對於追溯到任一版本的需要,所以,提交時所寫下的提交記錄訊息,就顯得十分重要,因為,這些訊息能協助我們,理解版本的變遷歷史經過。當然,你也可以隨意寫下任何形式的提交訊息,但是,為了更有效的達成一些目的,我們可以寫下「更好」的提交訊息。而且,好的提交訊息,不只可以幫助我們理解版本變化的歷史及緣由,還可以帶來其他好處。

提交訊息可以協助團隊成員間的知識流動,團隊成員可以透過察看其他成員的提交訊息,來了解其他成員的工作進展,以及工作的內容。在察看的過程中,他可能對某一則提交訊息感興趣,例如,對其他成員增加某一功能或修正某一問題的手法,覺得好奇,便可以取出提交的內容來研究,那麼就可以藉此明白其他成員解決問題的方式。

在一個團隊裡,這就可以構成一個知識和技巧流動的方式。尤其是在實戰中觀摩高手的寫作及設計方式,對新手來說,有時候可以因此成長得很快;對於專案進度的管理者而言,透過提交的記錄訊息,也很容易明白團隊中的每個開發者的進展。而這種透過提交訊息的溝通方式,可以在不需要面對面討論或舉行會議的情況下,隨時隨地發生。若是團隊中有施行程式碼審閱(code review)的制度及流程,那麼,提交訊息的內容也有助於程式碼審閱者,了解自己所審閱的內容究竟為何。

而團隊在完成所規畫的發行(release)目標後,在進行發行動作的同時,通常都會撰寫所謂的發行說明(release note),用來標註該發行所增加的功能、所修改的問題,以及尚未解決的已知問題等等。倘若版本控制系統中有著完整歷程的提交記錄,那麼,從前一次發行至本次發行間的提交記錄,便能夠輔助發行說明的撰寫,因為這些提交記錄詳實記錄著,自前一次發行至本次發行間的所有修改內容。有了提交記錄,發行說明的撰寫可以更容易,也不易有所疏漏。

提交記錄既然如此重要,又能帶給團隊諸般好處,那麼如何寫下好的提交記錄訊息這個議題,我們自然要重視。

提交記錄的寫法

一般來說,提交訊息是由兩個欄位所組成的,一個是摘要或標題,第二個則是細節的描述。

還記得我們在前文中強調過每次的提交內容最好都是「不可分割(atomic)」嗎?這代表它是一個最小但完整的提交內容。當你在撰寫摘要時,如果你發現打算描述的提交內容過大、而又可再切割時,就代表有必要再進行分割。

提交記錄訊息的標題,應該要精確、簡短的描述提交內容所完成的事。因為其他人察看提交歷史時,首先會看到的,便是各條提交記錄訊息的標題或摘要,所以最好是能一行之內,簡短地描述完畢。此外,有些人可能會寫下不夠精確的標題,例如:「修正了 XXX 功能的 bug」,而這個bug是什麼?從標題上完全看不出來。

一般來說,對於標題或摘要,版本控制系統都沒有既定的格式,所以撰寫者可以自由填寫。但是,若是導入一些預先定義好的格式,以及撰寫慣例,應該也會有所幫助。例如,有人就提出在標題上標註該提交的類型,例如究竟是增加功能(New)、修正問題(Fix)、改進(Enhancement)等等。例如,我們可以寫「[Fix #3129] XXX 功能無法正常載入圖片」,這代表目前解決的是錯誤追蹤系統上號碼為3129號的臭蟲,而標題內容,也是從錯誤追蹤系統上對臭蟲的描述抄寫過來的。

這麼一來,除了可以增加提交訊息的可讀性之外,也將提交訊息的標題寫法予以格式化,對於要利用一些自動化的文字工具來處理,就方便多了。例如,如此便可以利用文字搜尋工具,來尋找自己關心的提交記錄。

提交訊息的標題格式除了對應至錯誤追蹤系統上的項目之外,也可以考慮對應至規格項目的編號,或是設計項目的編號。這可以讓搜尋訊息者,更輕易找到他想找到的訊息。

提交記錄的標題,要表示的是「什麼(What)」,而至於提交內容的「如何(How)」,以及更細節性的「什麼(What)」,便可以在描述的部份來撰寫。在「 如何」的部份,要盡量以高階的方式來描述,畢竟低階細節的事項,透過閱讀程式碼來明白即可。在這邊的目的,是盡可能簡短又精確的讓讀者明白提交內容是透過什麼方式來處理的。此外,在套用此提交內容後的結果、狀態或可能存在的副作用,也可以在描述中填寫。

事實上,在每次開始工作之前,你都可以自己思考這次的提交訊息,究竟要如何填寫,以此決定工作的範圍。這有助於聚焦自己正要努力的方向及範圍,也可以讓開發更有步調和節奏。

剛開始撰寫提交訊息時,或許有些開發者會覺得麻煩、增加了額外的負擔。但是,正如本文所提到的,提交訊息對日後的開發,可以產生很多的助益。千萬別為了怕添麻煩,而省去這個重要的動作。

專欄作者


熱門新聞

Advertisement