== Dev Week -- Writing Crisp Changelogs -- coolbhavi -- Thu, 3rd Feb, 2012 ==
{{{#!irc
[17:00] <coolbhavi> Hi all I am Bhavani Shankar a 24 year old ubuntu developer from India
[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
[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
[17:01] <coolbhavi> So lets start :)
[17:01] <coolbhavi> == Meaning of a changelog ==
[17:01] <coolbhavi> A changelog is nothing but a log or record of changes made to a project or a software
[17:02] <coolbhavi> == The basic funda behind a Changelog ==
[17:02] <coolbhavi> Naming convention of a changelog file generally is a txt file with a name as ChangeLog
[17:02] <coolbhavi> Sometimes its also called by CHANGES or HISTORY
[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)
[17:03] <coolbhavi> Some Version control systems are able to generate the relevant information that is suited as a changelog.
[17:03] <coolbhavi> == General Format of a changelog file ==
[17:03] <coolbhavi> Most changelog files follow the following format
[17:03] <coolbhavi> YYYY-MM-DD  Joe Hacker  <joe@hacker.com>
[17:03] <coolbhavi>     * myfile.ext (myfunction): my changes made
[17:03] <coolbhavi>     additional changes
[17:03] <coolbhavi>     * myfile.ext (unrelated_change): my changes made
[17:03] <coolbhavi>     to myfile.ext but completely unrelated to the above
[17:03] <coolbhavi>     * anotherfile.ext (somefunction): more changes
[17:04] <coolbhavi> (These files are generally organised by paragraphs defining a unique change wrt a function or a file)
[17:04] <coolbhavi> More on changelogs and changelog formats here: http://www.gnu.org/prep/standards/html_node/Change-Logs.html
[17:05] <coolbhavi> ok now moving on,
[17:05] <coolbhavi> == Ubuntu and Changelogs ==
[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
[17:05] <coolbhavi> Debian policy defines its changelog to be in this format:
[17:05] <coolbhavi> package (version) distribution(s); urgency=urgency
[17:05] <coolbhavi>      	    [optional blank line(s), stripped]
[17:05] <coolbhavi>        * change details
[17:05] <coolbhavi>          more change details
[17:05] <coolbhavi>      	    [blank line(s), included in output of dpkg-parsechangelog]
[17:06] <coolbhavi>        * even more change details
[17:06] <coolbhavi>      	    [optional blank line(s), stripped]
[17:06] <coolbhavi>       -- maintainer name <email address>[two spaces]  date
[17:06] <coolbhavi> In particular, The date has the following format:
[17:06] <coolbhavi>      day-of-week, dd month yyyy hh:mm:ss +zzzz
[17:07] <coolbhavi> which is got by running the date -R command in a terminal
[17:07] <coolbhavi> where:
[17:07] <coolbhavi>     day-of week is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun
[17:07] <coolbhavi>     dd is a one- or two-digit day of the month (01-31)
[17:07] <coolbhavi>     month is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
[17:07] <coolbhavi>     yyyy is the four-digit year (e.g. 2012)
[17:07] <coolbhavi>     hh is the two-digit hour (00-23)
[17:07] <coolbhavi>     mm is the two-digit minutes (00-59)
[17:07] <coolbhavi>     ss is the two-digit seconds (00-60)
[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.
[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)
[17:09] <coolbhavi> for more info on the dch command please see man dch
[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
[17:10] <coolbhavi> Now moving on further
[17:10] <coolbhavi> == Do's and Donts ==
[17:11] <coolbhavi> <kanliot> QUESTION:  When are changelogs used, and who is responsible for putting them in.  also, where are they placed?
[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
[17:14] <coolbhavi> so moving on with do's and donts
[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 :)
[17:15] <coolbhavi> Below are few points to effective changelog writing
[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
[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
[17:16] <coolbhavi> Grouping: Group the common stuff and related changes under a heading called summary to make it easier to understand
[17:16] <coolbhavi> Whitespaces: Give appropriate whitespaces to make a clean looking formatted changelog
[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
[17:17] <coolbhavi> Closing the bugs via changelog while submitting a patch to a bug for sponsor review
[17:17] <coolbhavi> last but not the least, spellchecks!
[17:18] <coolbhavi> The following link gives few examples of debian/changelog writing http://pastebin.com/kQHazZ8y
[17:19] <coolbhavi> Please Remember that changelog writing becomes easy by practice!
[17:19] <coolbhavi> Sorry for hurrying the session up due to 30 min time slot
[17:20] <ClassBot> There are 10 minutes remaining in the current session.
[17:20] <coolbhavi> Please feel free to ask any questions on the same
[17:24] <coolbhavi> <kanliot> QUESTION ARE you going to go into the actual command to generate the changelogs?
[17:25] <ClassBot> There are 5 minutes remaining in the current session.
[17:26] <coolbhavi> after you type the changelog  debuild will use dpkg-parsechangelog and dpkg-genchanges to generate a changes file
[17:26] <coolbhavi> QUESTION: are the * - and + in that example file just arbitrary bullet points or do they have a special meaning in changelogs?
[17:27] <coolbhavi> the bullet points are used for distinguishing between the main summary of changes and a detailed description for formatting
[17:28] <coolbhavi> <jincreator> QUESTION: Sometimes my changelog sentence become too log for 1 line. What is the best way to solve it?
[17:28] <coolbhavi> wrap up the line to be around 80 charecters
[17:28] <coolbhavi> <jsjgruber-lernid> QUESTION: ​ Should you create changelogs before or after you merge changes into a repo?
[17:29] <coolbhavi> after doing the changes before merging the same its always preferable to document changes
[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.
[17:30] <coolbhavi> You can also catch me up on bhavi@ubuntu.com or facebook.com/bshankar
[17:30] <coolbhavi> Thanks all again!
}}}