emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Clarification on ChangeLog documentation
@ 2014-03-14 16:09 John Hendy
  2014-03-15  6:28 ` Bastien
  2014-03-15 15:17 ` John Hendy
  0 siblings, 2 replies; 4+ messages in thread
From: John Hendy @ 2014-03-14 16:09 UTC (permalink / raw)
  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


>

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2014-03-17  1:08 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-03-14 16:09 Clarification on ChangeLog documentation John Hendy
2014-03-15  6:28 ` Bastien
2014-03-15 15:17 ` John Hendy
2014-03-17  1:08   ` Bastien

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).