Clarification on ChangeLog documentation

Clarification on ChangeLog documentation

[John Hendy]

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


>

Re: Clarification on ChangeLog documentation

[Bastien]

Hi John,

I tried to clarify the org-contribute.org again.

Let me know if this addresses the issues you were
reporting.

Thanks,

-- 
 Bastien

Re: Clarification on ChangeLog documentation

[John Hendy]

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

Re: Clarification on ChangeLog documentation

[Bastien]

Hi John,

John Hendy <jw.hendy@gmail.com> writes:

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

This is the standard way a Changelog file looks like.

Try adding chanlog entries with C-x 4 a.

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

Yes, exactly.

>> #+begin_quote
>> Modified from a patch proposal by Johan Friis.
>> #+end_quote
>>
>> Can I reference mailing list threads, or is this not advised?

You are encouraged to reference mailing list threads and/or
previous commits refs, for sure.

>> Or
>> should I be mentioning the person who responded on the mailing list
>> for the clarification which led to the documentation modification?

Up to you.  There are no real conventions in this part: add what you
think is useful for groking the how and why of the commit.

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

The limit is a cumulative change of 20 non-repetitive change
lines.

Best,

-- 
 Bastien