From mboxrd@z Thu Jan 1 00:00:00 1970 From: John Hendy Subject: Clarification on ChangeLog documentation Date: Fri, 14 Mar 2014 11:09:53 -0500 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:41139) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOUgF-0004LP-N5 for emacs-orgmode@gnu.org; Fri, 14 Mar 2014 12:09:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WOUgE-0005or-91 for emacs-orgmode@gnu.org; Fri, 14 Mar 2014 12:09:55 -0400 Received: from mail-yh0-x22b.google.com ([2607:f8b0:4002:c01::22b]:42445) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOUgE-0005ol-4r for emacs-orgmode@gnu.org; Fri, 14 Mar 2014 12:09:54 -0400 Received: by mail-yh0-f43.google.com with SMTP id b6so2737717yha.2 for ; Fri, 14 Mar 2014 09:09:53 -0700 (PDT) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode Greetings, I've been getting my feet wet on documentation patches (well, on two of them) recently and didn't think the documentation was *that* clear, in my opinion. If someone can help clarify, I'm happy to patch the documentation on patching :) For reference: - http://orgmode.org/worg/org-contribute.html#sec-5 The specification is clear enough for lines 1 and 2. #+begin_quote In line 3, the ChangeLog entry should start, in a similar format as in the old ChangeLog files, but without the author information (which is part of the commit anyway). #+end_quote The ChangeLog instructions refer back to the "old ChangeLog" files ,but if you've never submitted a patch, that's not very helpful and there's no link to read about the "old" format. I referred to the example for this, but more on that below. #+begin_quote Variables and functions names are quoted like =`this'= (backquote and single quote). #+end_quote Does the Org verbatim markup help explain this any better than just using, `this'? It's not fontified, so to an Org-novice, it might not be clear why == surround the word. And, walking through the example line by line: #+begin_quote Capture: Fix the case of using a template file #+end_quote What determines what should come before the colon? Obviously the example was to capture functionality and the corresponding documentation, but is there a set list of words that should be used? A recent patch, for example, clarified that the :exports header argument only applied to code blocks, not inline code. I used: Header arguments: blah blah blah Should that have been a manual section title, something specifically about exporting, code blocks, babel... other? I understand the first line should contain the file name. Is this correct, as it's not in the manual example. And should it be file.ext, or dir/file.ext for the first line summary? #+begin_quote: * lisp/org-capture.el (org-capture-set-plist): Make sure txt is a string before calling `string-match'. (org-capture-templates): Fix customization type. * doc/org.texi (Capture): Document using a file for a template. #+end_quote My change modified only org.texi, but in two places. Do I need a "header" per change, or just a header per file? Nevermind; Bastien responded to my submission so I now know the answer is one header, with two content bits. Also, from his response, I gather that the bit in between parentheses should be the @node name of the section being changed, correct? #+begin_quote: The problem here was that a wrong keyword was given in the customization type. This let to a string-match against a list value. #+end_quote I couldn't tell if this paragraph was supposed to be a continuation of the second "header" above, or if it was it's own standalone summary of the gist of both changes. #+begin_quote Modified from a patch proposal by Johan Friis. #+end_quote Can I reference mailing list threads, or is this not advised? Or should I be mentioning the person who responded on the mailing list for the clarification which led to the documentation modification? #+begin_quote TINYCHANGE #+end_quote Is the FSF requirement necessary only if one commit > x lines, or is it cumulative? I can take a shot at clarifying this in the manual example based on responses to the above, if desired. I'm just getting up to speed, so perhaps it's just me that's ignorant on the process :) Best regards, John >