Re: Clarification on ChangeLog documentation

[John Hendy <jw.hendy@gmail.com>]

Hi Bastien,


Thanks for the changes; comments below:

On Fri, Mar 14, 2014 at 11:09 AM, John Hendy <jw.hendy@gmail.com> wrote:
> Greetings,
>
>
[snip]

> 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.
>

In the example provided, the first asterisk lists a file and two
changed nodes. Why is the third just parentheses with no file.
Assumption: it's also in org-timer.el, but the description of the
change just wouldn't have matched the other two.


> #+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.
>

Thanks for changing!

> 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?
>

Clarified now. file-name: blah blah.


> #+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?
>

I think this is now resolved for me as well.

> #+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.
>

Taking this to be general elaboration about /both/ changes; i.e. a
summary of the motivation of the changes in general.

> #+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?
>

Still not sure about this.

> #+begin_quote
> TINYCHANGE
> #+end_quote
>
> Is the FSF requirement necessary only if one commit > x lines, or is
> it cumulative?
>

Also not sure about this, but I've seen enough FSF forms asked for
that I assume I'll be asked if I hit whatever the limit is.

> 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 :)


Thanks for adding the new info!
John


>
>
> Best regards,
> John
>
>
>>