Difference between revisions of "Contributing to GnuCash"

From GnuCash
Jump to: navigation, search
(Emacs Style Settings: Moving to the emacs page)
(Code: Rework a bit.)
Line 16: Line 16:
  
 
If you're a programmer, obviously a good way to help is to start writing useful 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.
+
* See [[Building]] for more details on how to build the program from source code.
 +
* We use [http://subversion.tigris.org/ Subversion] as our primary Version Control System. There is an official [http://git-scm.com/ Git] mirror on [https://github.com/Gnucash/Gnucash Github]. Detailed instructions for using each are provided on the [[Subversion]] page.
 +
* Please subscribe to the [[Mailing Lists]] and introduce yourself to the development team. You can also hang out on [[IRC]], but that isn't required.
 
* Read the two files [http://svn.gnucash.org/trac/browser/gnucash/trunk/HACKING HACKING] and [http://svn.gnucash.org/trac/browser/gnucash/trunk/README.svn README.svn].
 
* Read the two files [http://svn.gnucash.org/trac/browser/gnucash/trunk/HACKING HACKING] and [http://svn.gnucash.org/trac/browser/gnucash/trunk/README.svn README.svn].
** 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.
+
* Now try your hand at one of the outstanding bugs in [[Bugzilla]], something from the [[WishList]] or your own pet peeve.
 +
** The '''coding style''' was last discussed on the [http://lists.gnucash.org/pipermail/gnucash-devel/2009-August/026121.html gnucash-devel ML].
 
** 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]].
 
** If your code adds or changes some functionality, do not forget the '''documentation''':
 
** If your code adds or changes some functionality, do not forget the '''documentation''':
*** The main point for ''source documentation'' is [[Doxygen]].
+
*** We use [http://www.stack.nl/~dimitri/doxygen DOxygen] to document the sources, including the C API. Details about our use are on the [[Doxygen]] wiki page.
 
*** Try to keep the ''README files'' and that in ''src/doc'' up to date.
 
*** Try to keep the ''README files'' and that in ''src/doc'' up to date.
 
*** Update the relevant sections in '''help''' and '''guide'''.
 
*** 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>)
+
* Once you have your changes written and well tested, you'll want to submit it so that someone with commit privilege can add it to the official sources. First, make a 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.
+
** Git is best, you can write up a commit message, commit it to your local repo, and run
** 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.
+
  git format-patch HEAD^
** If you insist on mailing a patch to gnucash-devel, it should be attached, not inlined.
+
to make a patch with your commit message included. The commit message should look like
** If the patch is non-trivial, consider detailing what it does as well in the bug report.
+
  [Bug 123456] Bug Title
* See [[Building]] for more details on how to build the program from source code.
+
 
 +
 
 +
  A nice description of what the patch does.
 +
 
 +
**If you're using Subversion, you can create a patch with
 +
  svn diff
 +
** If there's already a bug about it in [[Bugzilla]], just attach the patch to the bug. Be sure to check the "patch" checkbox on the attachment form.  
 +
** If there isn't a bug already (be sure to search!), it really works best if you create a new one to attach your patch to.
 +
*** Describe the problem or improvement that your patch addresses in the initial comment.
 +
*** If you use Git, open the bug ''before'' you make your patch so that you can include the bug number in the commit message.
 +
** If there isn't a bug already and the patch is trivial, you can send it to the '''gnucash-devel''' mailing list (though we really do prefer patches to go to [[Bugzilla]]).
 +
*** Please attach the patch to the email, don't inline it in the message, even if you used git format-patch and it made a pretty email for you.
  
 
== Tools ==
 
== Tools ==

Revision as of 01:17, 23 November 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 :).

  • See Building for more details on how to build the program from source code.
  • We use Subversion as our primary Version Control System. There is an official Git mirror on Github. Detailed instructions for using each are provided on the Subversion page.
  • Please subscribe to the Mailing Lists and introduce yourself to the development team. You can also hang out on IRC, but that isn't required.
  • Read the two files HACKING and README.svn.
  • Now try your hand at one of the outstanding bugs in Bugzilla, something from the WishList or your own pet peeve.
    • The coding style was last discussed on the gnucash-devel ML.
    • 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:
      • We use DOxygen to document the sources, including the C API. Details about our use are on the Doxygen wiki page.
      • Try to keep the README files and that in src/doc up to date.
      • Update the relevant sections in help and guide.
  • Once you have your changes written and well tested, you'll want to submit it so that someone with commit privilege can add it to the official sources. First, make a patch:
    • Git is best, you can write up a commit message, commit it to your local repo, and run
 git format-patch HEAD^

to make a patch with your commit message included. The commit message should look like

 [Bug 123456] Bug Title
 
 
 A nice description of what the patch does.
    • If you're using Subversion, you can create a patch with
 svn diff
    • If there's already a bug about it in Bugzilla, just attach the patch to the bug. Be sure to check the "patch" checkbox on the attachment form.
    • If there isn't a bug already (be sure to search!), it really works best if you create a new one to attach your patch to.
      • Describe the problem or improvement that your patch addresses in the initial comment.
      • If you use Git, open the bug before you make your patch so that you can include the bug number in the commit message.
    • If there isn't a bug already and the patch is trivial, you can send it to the gnucash-devel mailing list (though we really do prefer patches to go to Bugzilla).
      • Please attach the patch to the email, don't inline it in the message, even if you used git format-patch and it made a pretty email for you.

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


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