Dev Week -- Writing Crisp Changelogs -- coolbhavi -- Thu, 3rd Feb, 2012
1 [17:00] <coolbhavi> Hi all I am Bhavani Shankar a 24 year old ubuntu developer from India 2 [17:00] <coolbhavi> I am going to take you through what is meant by a changelog in general and how to write effective changelogs in the ubuntu sphere 3 [17:01] <coolbhavi> Before we start off please download a package (totem for instance) and when we navigate through the source tree we find files named ChangeLog, NEWS, et.al 4 [17:01] <coolbhavi> So lets start :) 5 [17:01] <coolbhavi> == Meaning of a changelog == 6 [17:01] <coolbhavi> A changelog is nothing but a log or record of changes made to a project or a software 7 [17:02] <coolbhavi> == The basic funda behind a Changelog == 8 [17:02] <coolbhavi> Naming convention of a changelog file generally is a txt file with a name as ChangeLog 9 [17:02] <coolbhavi> Sometimes its also called by CHANGES or HISTORY 10 [17:02] <coolbhavi> (It may be brought to notice that sometimes some packages/software have a file called NEWS is usually a different file reflecting changes between releases, not between the commits) 11 [17:03] <coolbhavi> Some Version control systems are able to generate the relevant information that is suited as a changelog. 12 [17:03] <coolbhavi> == General Format of a changelog file == 13 [17:03] <coolbhavi> Most changelog files follow the following format 14 [17:03] <coolbhavi> YYYY-MM-DD Joe Hacker <email@example.com> 15 [17:03] <coolbhavi> * myfile.ext (myfunction): my changes made 16 [17:03] <coolbhavi> additional changes 17 [17:03] <coolbhavi> * myfile.ext (unrelated_change): my changes made 18 [17:03] <coolbhavi> to myfile.ext but completely unrelated to the above 19 [17:03] <coolbhavi> * anotherfile.ext (somefunction): more changes 20 [17:04] <coolbhavi> (These files are generally organised by paragraphs defining a unique change wrt a function or a file) 21 [17:04] <coolbhavi> More on changelogs and changelog formats here: http://www.gnu.org/prep/standards/html_node/Change-Logs.html 22 [17:05] <coolbhavi> ok now moving on, 23 [17:05] <coolbhavi> == Ubuntu and Changelogs == 24 [17:05] <coolbhavi> The changelog file pertaining to a Ubuntu package is stored in the debian directory under the name changelog according to debian policy 25 [17:05] <coolbhavi> Debian policy defines its changelog to be in this format: 26 [17:05] <coolbhavi> package (version) distribution(s); urgency=urgency 27 [17:05] <coolbhavi> [optional blank line(s), stripped] 28 [17:05] <coolbhavi> * change details 29 [17:05] <coolbhavi> more change details 30 [17:05] <coolbhavi> [blank line(s), included in output of dpkg-parsechangelog] 31 [17:06] <coolbhavi> * even more change details 32 [17:06] <coolbhavi> [optional blank line(s), stripped] 33 [17:06] <coolbhavi> -- maintainer name <email address>[two spaces] date 34 [17:06] <coolbhavi> In particular, The date has the following format: 35 [17:06] <coolbhavi> day-of-week, dd month yyyy hh:mm:ss +zzzz 36 [17:07] <coolbhavi> which is got by running the date -R command in a terminal 37 [17:07] <coolbhavi> where: 38 [17:07] <coolbhavi> day-of week is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun 39 [17:07] <coolbhavi> dd is a one- or two-digit day of the month (01-31) 40 [17:07] <coolbhavi> month is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec 41 [17:07] <coolbhavi> yyyy is the four-digit year (e.g. 2012) 42 [17:07] <coolbhavi> hh is the two-digit hour (00-23) 43 [17:07] <coolbhavi> mm is the two-digit minutes (00-59) 44 [17:07] <coolbhavi> ss is the two-digit seconds (00-60) 45 [17:07] <coolbhavi> +zzzz or -zzzz is the the time zone offset from Coordinated Universal Time (UTC). "+" indicates that the time is ahead of (i.e., east of) UTC and "-" indicates that the time is behind (i.e., west of) UTC. The first two digits indicate the hour difference from UTC and the last two digits indicate the number of additional minutes difference from UTC. The last two digits must be in the range 00-59. 46 [17:08] <coolbhavi> It can be worth mentioning here that the entire changelog must be coded in UTF-8 (normally taken care by dch command) 47 [17:09] <coolbhavi> for more info on the dch command please see man dch 48 [17:10] <coolbhavi> More explanation on the fields of the changelog file here: http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog 49 [17:10] <coolbhavi> Now moving on further 50 [17:10] <coolbhavi> == Do's and Donts == 51 [17:11] <coolbhavi> <kanliot> QUESTION: When are changelogs used, and who is responsible for putting them in. also, where are they placed? 52 [17:14] <coolbhavi> kanliot, changelogs are used as a log for tracking changes in projects or software usually the project maintainers write the changelogs its usually placed in the source tree under the name ChangeLog with a txt extension normally and in debian/ubuntu the package chanelogs are placed in debian/changelog 53 [17:14] <coolbhavi> so moving on with do's and donts 54 [17:15] <coolbhavi> The purpose of writing a changelog generally is to make sure you document all the changes and history in a most readable n understandable manner :) 55 [17:15] <coolbhavi> Below are few points to effective changelog writing 56 [17:15] <coolbhavi> Fewer Assumptions: Try to make lesser assumptions about a particular user knowing something about a particular package so it ll help bringing out better detail and understandability 57 [17:16] <coolbhavi> Start with the easiest part first and push the more complex/more technical part at the end to make it a interesting read 58 [17:16] <coolbhavi> Grouping: Group the common stuff and related changes under a heading called summary to make it easier to understand 59 [17:16] <coolbhavi> Whitespaces: Give appropriate whitespaces to make a clean looking formatted changelog 60 [17:17] <coolbhavi> Summarising: Adding a one line summary of the change at the top makes the reader to get a overview of what the change is meant to be 61 [17:17] <coolbhavi> Closing the bugs via changelog while submitting a patch to a bug for sponsor review 62 [17:17] <coolbhavi> last but not the least, spellchecks! 63 [17:18] <coolbhavi> The following link gives few examples of debian/changelog writing http://pastebin.com/kQHazZ8y 64 [17:19] <coolbhavi> Please Remember that changelog writing becomes easy by practice! 65 [17:19] <coolbhavi> Sorry for hurrying the session up due to 30 min time slot 66 [17:20] <ClassBot> There are 10 minutes remaining in the current session. 67 [17:20] <coolbhavi> Please feel free to ask any questions on the same 68 [17:24] <coolbhavi> <kanliot> QUESTION ARE you going to go into the actual command to generate the changelogs? 69 [17:25] <ClassBot> There are 5 minutes remaining in the current session. 70 [17:26] <coolbhavi> after you type the changelog debuild will use dpkg-parsechangelog and dpkg-genchanges to generate a changes file 71 [17:26] <coolbhavi> QUESTION: are the * - and + in that example file just arbitrary bullet points or do they have a special meaning in changelogs? 72 [17:27] <coolbhavi> the bullet points are used for distinguishing between the main summary of changes and a detailed description for formatting 73 [17:28] <coolbhavi> <jincreator> QUESTION: Sometimes my changelog sentence become too log for 1 line. What is the best way to solve it? 74 [17:28] <coolbhavi> wrap up the line to be around 80 charecters 75 [17:28] <coolbhavi> <jsjgruber-lernid> QUESTION: â€‹â€†Should you create changelogs before or after you merge changes into a repo? 76 [17:29] <coolbhavi> after doing the changes before merging the same its always preferable to document changes 77 [17:30] <coolbhavi> Thanks all of you for turning up :) Please feel free to hang out at #ubuntu-motu or #ubuntu-devel for any questions. 78 [17:30] <coolbhavi> You can also catch me up on firstname.lastname@example.org or facebook.com/bshankar 79 [17:30] <coolbhavi> Thanks all again!