Difference between revisions of "Contributing to GnuCash"

From GnuCash
Jump to: navigation, search
(Note of intent: changing svn to git after version 2.6)
m (Getting started on the GnuCash Wiki: Minor fixups)
(16 intermediate revisions by 5 users not shown)
Line 3: Line 3:
 
Many ideas here are taken from this slashdot [http://slashdot.org/comments.pl?sid=74382&cid=6671463 comment].
 
Many ideas here are taken from this slashdot [http://slashdot.org/comments.pl?sid=74382&cid=6671463 comment].
  
 +
If you ever used GnuCash, you were already ...
 
== Testing ==
 
== 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. Programmers should feel free to add plenty of unit tests (see [[Testing]]) as well.
 
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. Programmers should feel free to add plenty of unit tests (see [[Testing]]) as well.
  
 +
Resulting on your tests, you should give us some ...
 
== Feedback ==
 
== 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 [http://slashdot.org/comments.pl?sid=74382&cid=6671086 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,"
 
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 [http://slashdot.org/comments.pl?sid=74382&cid=6671086 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 [[FAQ#Q: What should I obey as a beginner in bug reporting, enhacement requesting ...?|this section]] and following of the [[FAQ]].
+
Possible ways of feedback are explained in [[FAQ#Q:_What_are_the_basics_of_bug_reporting_and_enhacement_requesting?|this section]] and following of the [[FAQ]].
  
== WishList ==
+
=== 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]].
+
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]], but the developers prefer that you post your enhancement requests into [[Bugzilla]] or try the new [http://gnucash.uservoice.com "Uservoice" Feature Request Forum].
  
== Documentation ==
+
If you are mostly satisfied, tell it your friends:
  
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 ==
  
=== Wiki ===
+
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 [http://en.wikipedia.org/wiki/Linux_User_Group LUG]s can be invaluable for getting a larger userbase (and therefore hopefully a larger developer base).
  
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 [https://addons.mozilla.org/firefox/351/ Wikipedia editing extensions] to make the job easier.
+
If you have really no time over, you can also spent some ...
 +
== Money ==
  
== Localisation ==
+
The GnuCash Project encourages financial contributions in several ways as described on the [http://www.gnucash.org/donate.phtml donations page] of the main website.
  
If your natural language is different from english, you can contribute by translating
+
In addition to the suggestions there, you can make sizable donations to specific developers to help fulfill feature requests.
* parts of this wiki
 
* the [http://www.gnucash.org website]
 
* the program
 
* its official documentation "Help" and "Tutorial and concepts guide"
 
See [[Translation]] for details.
 
  
* Add or improve [[Translation#How_to_translate_the_files_containing_the_new_account_hierarchies|Account Templates]] for your region.
+
And thanking developers for past work can be done individually, but will not be done through the project.
* Add or improve Tax Reports for your region, which might be nontrivial. But adding a wiki page with [links to] tax forms or the description of the online interface of your tax authority could be a first step as programmers are seldom Certified Public Accountants, too.
 
  
* You could also support the [[Mailing Lists]] team of your language.
+
== Documentation ==
  
See also [[#Tools]].
+
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 ==
+
=== Wiki ===
  
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 [http://en.wikipedia.org/wiki/Linux_User_Group LUG]s can be invaluable for getting a larger userbase (and therefore hopefully a larger developer base).
+
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.
  
== Code ==
+
====Getting started on the GnuCash Wiki====
 +
You'll need an account. Unfortunately we've been beset by robot accounts and spammers over the last few years and now require contributors to [[Special:UserLogin/signup|request an account]]. This is human-moderated and you must convince the human that you're not a spammer or a robot. Don't bother requesting an account until you see something you want to change. Fill out the request form and explain in the "Reason" box exactly what you want to change and why. General descriptions of your skills aren't useful and will be ignored. If you've been contributing on the mailing list mention that with your email address (the request form isn't public, only wiki admins can see what you enter).
  
If you're a programmer, obviously a good way to help is to start writing useful code :).
+
When your account is approved, you will receive an email with a temporary password.  You should be able to log into the Wiki and change your password.  At first you have just minimal [[Special:ListGroupRights|user rights]], allowing you enhanced reading ability, namely that you can add pages to a personal watchlist.  To be able to edit any pages, you need ''emailconfirmed'' status.  To get that, click on "Preferences", see your "User profile", and select the option to confirm your email, which sends an email to your personal email account.  In your personal email software, find that email and click on the link it provides.  You may or may not need to log out and log back in again.  Under Preferences, you should see your membership in ''emailconfirmed'' group.
  
* See [[Building]] for more details on how to build the program from source code.
+
With ''emailconfirmed'' status, you still can't edit the [[GnuCash|GnuCash main page]], because it is protected for editing only by administrators (you will just see "View source" as a tab, but not "Edit"). At many other pages, you can now edit, although you cannot create new pages.
* 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. This includes commit conventions--e.g. backporting conventions. Note: We intend to switch to git after the release of version 2.6.
 
* 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].
 
* Now try your hand at one of the outstanding bugs in [[Bugzilla]], something from the [[WishList]] or your own pet peeve. Please consider adding unit tests (see [[Testing]]) for features where applicable.
 
** 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 adds or changes some functionality, do not forget the '''documentation''':
 
*** 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.
 
*** Update the relevant sections in '''help''' and '''guide'''.
 
* Once you have your changes written and well tested - <tt>make check</tt> will run a bunch of tests -, 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. See the [[Git#Patches|patch instructions]].
 
**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 ==
+
As of 2017, an ''emailconfirmed'' account will automatically further acquire ''autoconfirmed'' status after 7 days.  With that, you should be able to create new pages.
  
Text editors / IDE:
+
For most browsers ''Wikipedia editing extensions'' exist to make the job easier. To get one, search the addons page of your browser provider.
* Most developers seem to have used [[Emacs]] as IDE.
 
* Additionally there are some experiences with [[Eclipse]].
 
* Some are using qtcreator.
 
  
Build system:
+
===For Wikipedia editors===
* Gnucash uses the [http://en.wikipedia.org/wiki/Autotools Autotools] as build system
+
Wiki users who have edited in Wikipedia will find that the editing environment is similar.  It uses the same mediawiki software. With ''autoconfirmed'' status you may create your own user page and user Talk page.
* Additionally there are some experiments with [[CMake]], see [[Cutecash]]
 
  
== Money ==
+
== Localisation ==
  
The GnuCash Project encourages financial contributions in three ways:
+
If your natural language is different from english, you can contribute by translating
 +
* parts of this wiki,
 +
* the [http://www.gnucash.org website],
 +
* the messages of the program or
 +
* its official documentation "Help" and "Tutorial and concepts guide"
 +
See [[Translation]] for details.
  
# Small donations can go to the [http://sourceforge.net/donate/index.php?group_id=192 GnuCash tip jar] to pay for unavoidable expenses of the project, and for projects agreed upon by consensus.
+
* Add or improve [[Translation#How_to_translate_the_files_containing_the_new_account_hierarchies|Account Templates]] for your region.
# Sizable donations go to specific developers to help fulfill feature requests.
+
* Add or improve Tax Reports for your region, which might be nontrivial. But adding a wiki page with [links to] tax forms or the description of the online interface of your tax authority could be a first step as programmers are seldom Certified Public Accountants, too.
# Thanking developers for past work can be done individually, but will not be done through the project.
 
  
== See also ==
+
* You could also support the [[Mailing Lists]] team of your language.
  
See [[WishList]] for more ideas for small projects of value, ideal for limited contributors.
+
See also [[Development#Tools]].
  
An [https://lists.gnucash.org/pipermail/gnucash-devel/2004-June/011547.html informative mail] from the archives.
+
== Code ==
 
 
[http://svn.gnucash.org/docs/HEAD/ GnuCash design and developer's reference]
 
 
 
[http://www.gnu.org/software/guile/manual/html_node/Programming-in-Scheme.html Scheme programming manual]
 
  
[[C API]]
+
If you're a programmer, obviously a good way to help is to start writing useful code :). Please see [[Development]] for how to get started and [[Development Process]] for our procedures and guidelines.

Revision as of 13:46, 26 May 2017

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.

If you ever used GnuCash, you were already ...

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. Programmers should feel free to add plenty of unit tests (see Testing) as well.

Resulting on your tests, you should give us some ...

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.

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, but the developers prefer that you post your enhancement requests into Bugzilla or try the new "Uservoice" Feature Request Forum.

If you are mostly satisfied, tell it your friends:

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

If you have really no time over, you can also spent some ...

Money

The GnuCash Project encourages financial contributions in several ways as described on the donations page of the main website.

In addition to the suggestions there, you can make sizable donations to specific developers to help fulfill feature requests.

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

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.

Getting started on the GnuCash Wiki

You'll need an account. Unfortunately we've been beset by robot accounts and spammers over the last few years and now require contributors to request an account. This is human-moderated and you must convince the human that you're not a spammer or a robot. Don't bother requesting an account until you see something you want to change. Fill out the request form and explain in the "Reason" box exactly what you want to change and why. General descriptions of your skills aren't useful and will be ignored. If you've been contributing on the mailing list mention that with your email address (the request form isn't public, only wiki admins can see what you enter).

When your account is approved, you will receive an email with a temporary password. You should be able to log into the Wiki and change your password. At first you have just minimal user rights, allowing you enhanced reading ability, namely that you can add pages to a personal watchlist. To be able to edit any pages, you need emailconfirmed status. To get that, click on "Preferences", see your "User profile", and select the option to confirm your email, which sends an email to your personal email account. In your personal email software, find that email and click on the link it provides. You may or may not need to log out and log back in again. Under Preferences, you should see your membership in emailconfirmed group.

With emailconfirmed status, you still can't edit the GnuCash main page, because it is protected for editing only by administrators (you will just see "View source" as a tab, but not "Edit"). At many other pages, you can now edit, although you cannot create new pages.

As of 2017, an emailconfirmed account will automatically further acquire autoconfirmed status after 7 days. With that, you should be able to create new pages.

For most browsers Wikipedia editing extensions exist to make the job easier. To get one, search the addons page of your browser provider.

For Wikipedia editors

Wiki users who have edited in Wikipedia will find that the editing environment is similar. It uses the same mediawiki software. With autoconfirmed status you may create your own user page and user Talk page.

Localisation

If your natural language is different from english, you can contribute by translating

  • parts of this wiki,
  • the website,
  • the messages of the program or
  • its official documentation "Help" and "Tutorial and concepts guide"

See Translation for details.

  • Add or improve Account Templates for your region.
  • Add or improve Tax Reports for your region, which might be nontrivial. But adding a wiki page with [links to] tax forms or the description of the online interface of your tax authority could be a first step as programmers are seldom Certified Public Accountants, too.

See also Development#Tools.

Code

If you're a programmer, obviously a good way to help is to start writing useful code :). Please see Development for how to get started and Development Process for our procedures and guidelines.