Ubuntu Wiki

   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  <joe@hacker.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 bhavi@ubuntu.com or facebook.com/bshankar
  79 [17:30] <coolbhavi> Thanks all again!