Clarification on ChangeLog documentation

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

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


>