Difference between revisions of "Contributing to GnuCash"

From GnuCash
Jump to: navigation, search
(Feedback: Possible ways of feedback)
(Code: do not forget the documentation ...)
Line 21: Line 21:
 
** The '''coding style''' was last discussed on the [http://lists.gnucash.org/pipermail/gnucash-devel/2009-August/026121.html gnucash-devel ML]. Emacs users, see below for compatible settings.
 
** The '''coding style''' was last discussed on the [http://lists.gnucash.org/pipermail/gnucash-devel/2009-August/026121.html gnucash-devel ML]. Emacs users, see below for compatible settings.
 
** If your code will contain '''textual output for the user''', have a look at [[Translation#Tips_for_Developers | Translation: Tips for Developers]].
 
** If your code will contain '''textual output for the user''', have a look at [[Translation#Tips_for_Developers | Translation: Tips for Developers]].
** The main point for source documentation is [[Doxygen]].
+
** If your code adds or changes some functionality, do not forget the '''documentation''':
 +
*** The main point for ''source documentation'' is [[Doxygen]].
 +
*** Try to keep the ''README files'' and that in ''src/doc'' up to date.
 +
*** Update the relevant sections in '''help''' and '''guide'''.
 
* To create a patch do <tt>svn diff</tt> on ''trunk''. (When using [[git]], run <tt>git format-patch</tt>)
 
* To create a patch do <tt>svn diff</tt> on ''trunk''. (When using [[git]], run <tt>git format-patch</tt>)
 
* Once you are done, you should send your patch to the project. This can happen either by sending it to the [[Mailing Lists]] gnucash-devel directly, or by opening a new [[Bugzilla]] item and attach the patch as attachment there.
 
* Once you are done, you should send your patch to the project. This can happen either by sending it to the [[Mailing Lists]] gnucash-devel directly, or by opening a new [[Bugzilla]] item and attach the patch as attachment there.

Revision as of 12:48, 13 September 2011

The GnuCash Project is a volunteer-driven organization and depends on volunteers, such as you, to survive and grow. This page explains the ways to contribute to the project.

Many ideas here are taken from this slashdot comment.

Testing

Programmers can be fine testers, but non-programmers seem to be able to break programs in new and mysterious ways. The trick here is to learn how to give the best information to the programmers about how to reproduce bugs. A programmer will usually only be able to fix a bug they can see; if you can't make the programmer see your bug, it won't get fixed! If you find a real reproducible bug, check with Bugzilla to make sure the developers know about it.

Feedback

Providing feedback on what features are used, and what aren't is important to developers who may spend a lot of time on a feature they think is important instead of a feature that actually is important. From another comment: What this thing needs is some normal human beings using it and saying "you know what, it's NOT acceptable that window A obscures window B and freezes while window B is waiting for input from me." It needs, I am sorry to say, Quicken or MS Money users, who say "It was really easy to do X, Y, and Z, but here, I can't even figure out if it's possible,"

Possible ways of feedback are explained in this section and following of the FAQ.

Code

If you're a programmer, obviously a good way to help is to start writing useful code :).

  • Grab the latest Subversion trunk and try your hand at one of the outstanding bugs in Bugzilla or something on your personal WishList.
  • To get jump-started, you should get subscribed to the Mailing Lists. It might also be a good idea to hang out on IRC, but that is no requirement.
  • Read the two files HACKING and README.svn.
    • The coding style was last discussed on the gnucash-devel ML. Emacs users, see below for compatible settings.
    • If your code will contain textual output for the user, have a look at Translation: Tips for Developers.
    • If your code adds or changes some functionality, do not forget the documentation:
      • The main point for source documentation is Doxygen.
      • Try to keep the README files and that in src/doc up to date.
      • Update the relevant sections in help and guide.
  • To create a patch do svn diff on trunk. (When using git, run git format-patch)
  • Once you are done, you should send your patch to the project. This can happen either by sending it to the Mailing Lists gnucash-devel directly, or by opening a new Bugzilla item and attach the patch as attachment there.
    • Ideally, you should submit your patch into Bugzilla in any case so that it isn't easily forgotten. Additionally, you can send a message to gnucash-devel with a link to the newly created bugzilla item that explains your new contribution to inform other developers on your work.
    • If you insist on mailing a patch to gnucash-devel, it should be attached, not inlined.
    • If the patch is non-trivial, consider detailing what it does as well in the bug report.
  • See Building for more details on how to build the program from source code.

Tools

Text editors / IDE:

  • Most developers seem to have used Emacs as IDE.
  • Additionally there are some experiences with Eclipse.

Build system:

  • Gnucash uses the autotools as build system
  • Additionally there are some experiments with CMake, see Cutecash


Emacs Style Settings

Emacs users should add the following to their .emacs files:

 (c-add-style "gnucash"
               '("k&r"
                 (c-basic-offset . 4)
                 (c-offsets-alist . ((case-label . +)) )
                 (c-hanging-braces-alist . ((substatement-open before after)
                                             (block-close before after)) )
                 ))

Users with Emacs version 23 and later can add this as well:

 (dir-locals-set-class-variables 'gnucash-project
                               '((indent-tabs-mode . nil)
                                 (fill-column . 80)
                                 (c-mode . ((c-file-style . "gnucash")))
                                 (c++-mode . ((c-file-style . "gnucash")))))
 (dir-locals-set-directory-class "/path/to/gnucash-svn" 'gnucash-project)

Which will automatically apply the style (and ensure that indentation is done with spaces) to all C files in the given path. Users with earlier versions should at least add

 (setq indent-tabs-mode nil)

and should consider adding

 (c-default-style ('((c-mode . "gnucash"))))

Otherwise, you'll have to apply the gnucash style (Ctrl-c . Ret gnucash) to every file when you open it.

WishList

Similarly, it is important to keep track of wishlists — both those of the official developers, and of users. Since this is a wiki, a user named Andy Glew has taken the liberty of creating such a WishList.

Money

The GnuCash Project encourages financial contributions in three ways:

  1. Small donations can go to the GnuCash tip jar to pay for unavoidable expenses of the project, and for projects agreed upon by consensus.
  2. Sizable donations go to specific developers to help fulfill feature requests.
  3. Thanking developers for past work can be done individually, but will not be done through the project.

Documentation

Writing documents on how to do things, see e. g. Concept Guide, (or why to do things, accounting is a black art to many). Help people out using the program. The article said that the programmers are spending a lot of their time answering questions instead of actually getting on and doing the job. Even simple things like "Tips and tricks" are a good start. If users can help other users, then the current programmers can spend more of their time getting new developers up to speed.

Advocacy

You usually get developers because they use software and have an itch to scratch. I'd guess that GnuCash's biggest problem is that programmers don't use the software. Running tutorials, presentations at local LUGs can be invaluable for getting a larger userbase (and therefore hopefully a larger developer base).

Wiki

Write answers to FAQ's. Wiki'ing is very addictive and fun. And while you're at it, everyone learns! As you probably have noticed, you are looking at such a wiki right now. Simply click on the "Edit". If you are a Firefox user, you may like to try the Wikipedia editing extensions to make the job easier.

More

See WishList for more ideas for small projects of value, ideal for limited contributors.

An informative mail from the archives.

GnuCash design and developer's reference

Scheme programming manual