Re: How you can help

From: Sebastian Rose <sebastian_rose@gmx.de>
Cc: emacs-orgmode List <emacs-orgmode@gnu.org>
Subject: Re: How you can help
Date: Thu, 23 Oct 2008 12:28:37 +0200	[thread overview]
Message-ID: <490051D5.9060708@gmx.de> (raw)
In-Reply-To: <490042B4.1010303@gmx.de>

Sebastian Rose wrote:
> Should we put a page on worg by this name (see subject of this
> thread)? We could show, how to turn on debugging, write a good bug
> report, link to good elisp tutorials and describe how to use the elisp
> debugger in emacs for simple debugging.
> 
> If no one stops me, I'll do it these days. As or me, a page like that
> would be helpfull. I'll be back for report - maybe one of the lisp
> freaks could add some details later on?

Hm - there is a link to the 'Feedback' section of the manual
(http://orgmode.org/org.html#Feedback) on
http://orgmode.org/worg/org-contribute.php but

  1. It's hard to find. One has find worg (http://orgmode.org/worg/),
     and then click 'How to contribute to Org?' to get to
     http://orgmode.org/worg/org-contribute.php where the link is.
     I think I wouldn't follow the link 'How to contribute to Org', if
     I was to report a bug (maybe it's my bad english, but I lots of
     people whos english is even worse).

  2. While the 'Feedback' section in the manual is as good as the rest
     of it, it's short and does, for good reasons, not provide more
     information, than absolutely needed.

Suggestions:

   1. on Worgs startpage (http://orgmode.org/worg/): add an extra section
      (as the FIRST one) 'How you can help'.

   2. Under that headline, put the link to the 'Feedback' section of the
      manual.

   3. Add more links to one or more pages for tips on debugging etc.

   4. Add subdirectory for those debugging tips. We could also add things
      like coding conventions, notes about the APIs in org etc. to that
      directory.

....Please comment...

   5. I also think of little packages for testing parts of org.

      Example XHTML-export:

      When the HTML-exporter didn't work lately, I set up a little
      directory or testing. On top of that tree I had an Org-file with
      [[elisp:]] links to click on, like
      [[elisp:(setq debug-on-error t)]]
      or [[elisp:(debug-on-entry 'org-export-org-to)]] and one for
      loading a setup.el in the same directory (primaryly to adjust
      org-publish-project-alist - in principle, everything could be
      setup in that file, but needed two different setups for these
      tests).

      Now I can just open that Org-file, click on two or three links
      and get a backtrace, if something is wrong. It's so simple to
      test the exporter this way, that it takes 30 seconds or even less
      (on failure :-)

      With simple trees like that (eventually downloadable as *.tar.bz2)
      one may test a module with all the little corner cases, which
      might not be in the Org-files the tester uses for his daily work
      and without risk.

      If we encounter a new corner case, we could just add it to the
      test packages Org-files and document it in the packages index.org
      (or README.org) to prevent a regression.

      When working on a module, one could programm against those tests.

Creating and maintaining those test packages is a simple thing to do.
All it requires is knowledge of USING org and just a tiny little extra.
Hence I suppose this work should be done by the community/worgers.

It will be much more fun to add tested patches (and more secure to
create one)!

Regards,

   Sebastian

> Carsten Dominik wrote:
>> Hi Org users,
>>
>> I need to get control over the time I spent on developing
>> Org-mode.  Recently, I have again worked too hard on it, spending
>> more time than I should, in order to get 6.9 and 6.10 out and to
>> seize the chance to get the best possible version into Emacs
>> 23.1.
>>
>> However, this is getting out of control, and I am now putting
>> myself a hard limit of 1 hour per day, clocked by Org-mode, which
>> will clearly cut in on my development speed and posting rate.
>>
>> Here is how you can help me to make the most of that one hour.
>>
>> 1. If you report a bug, please try to do as much work as you can
>>    yourself.  Before you send it, think if you have collected all
>>    the information you can.  There are great examples of good bug
>>    reports on the list already.  The best bug reports are, of
>>    course, those that are accompanied by a patch.
>>
>> 2. If you are reading the list and see bug reports, consider
>>    putting in 10 minutes, trying to reproduce this problem
>>    yourself, and maybe adding information that might be useful
>>    for me to track down that bug.  Again, this is already
>>    happening, I am only trying to encourage this type of
>>    behavior.
>>
>> 3. I have recently spent much time on fixing bugs in parts of Org
>>    that I did not write myself, so this is taking much more time
>>    than usually.  If you know Emacs Lisp, and I know there are a
>>    number of excellent Lisp programmers on this group, consider
>>    "adopting" one of the following subsystems.  By "adoption", I
>>    mean that you make it your mission to deeply understand this
>>    part of Org, so that *you* will be in the position to fix
>>    bugs, taking that off my shoulders.
>>
>>    - org-publish.el.  I think the biggest bugs are out now, but I
>>      am sure this system can be improved quite a bit.  If you are
>>      that Lisp programmer trying to take up this task, consider
>>      teaming up with Sebastian Rose who is a great guy, has quite
>>      some understanding of that system and good ideas about it,
>>      but just is not enough of a Lisp programmer to really take
>>      that on.
>>
>>    - org-export-latex.el.  This is a tough one because you need
>>      to know both LaTeX and Lisp.  And the code is complex, in
>>      part because Org-mode allows to write LaTeX is a relatively
>>      lazy way.  Bastien has done a great great job capturing this
>>      into an exporter.  However, there are still problems and
>>      bugs, some came up recently on the list.  And Bastien
>>      currently does not have the time to contribute consistently.
>>      As a result, I have started to fix some bugs, but this is
>>      really eating too much of my time.  This subsystem can also
>>      use feature additions, for example better handling of image
>>      insertion, maybe with captions.  I have ideas about this, so
>>      talk to me if you want to help out.
>>
>> 4. Try to answer as many messages on the mailing list as you can.
>>    I have been trying hard to make sure that each and every
>>    reasonable question on the list (and this is really the only
>>    kind we get in this amazing community) will be answered.
>>    Doing this still takes a significant fraction of my Org-mode
>>    development time.  I will clearly spend less time on this in
>>    the future, in this way also giving others more time to
>>    answer.  Again, there are already quite a few people who
>>    regularly *answer* questions, and all I am trying to do here
>>    is encouraging this activity.
>>
>> 5. Help developing the Org-mode FAQ by adding useful information
>>    to it yourself.  All you need to do is to get acces to Worg,
>>    which will help getting to know git in the process.  Worg is
>>    meant to be user edited, so please go wild and add information
>>    and links at will.
>>
>> Thanks to you all, for your understanding and help.
>>
>> - Carsten
>>
>>
>>
>> _______________________________________________
>> Emacs-orgmode mailing list
>> Remember: use `Reply All' to send replies to the list.
>> Emacs-orgmode@gnu.org
>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>>
> 
> 
> 
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
> 