Updated Spanish translation
[anjuta.git] / HACKING
bloba0953350e4d91acd44094f69eedde078dfda3acd
1 Notes for Developers on contributing to Anjuta:
2 ----------------------------------------------
3 (To be expanded over time. Please post submissions to the Anjuta 
4 Development mailing list or the project maintainer)
6 Getting Started:
7 ---------------
9 First thing to do is to get a build working. Anjuta can be built using jhbuild,
10 which is the recommended way to build GNOME 2.x and Anjuta. It is advisable to
11 use '--enable-warnings --enable-debug' with configure while building anjuta if
12 you want to hack on it. Anjuta can be used to hack on Anjuta, and there is a
13 anjuta.anjuta project file in git for this purpose.
15 Once you have got anjuta built and loaded in itself, the most important thing
16 is to decide what to work on (the TODO, as you say). There are many directions
17 you can take. I'm listing some of the more common ones in order of difficulty.
19 0. Use it, test it, report bug, request features, etc. In short, become
20 an active user. That is how most people become anjuta developers.
22 1. Documentation and translation. While this might not be a very
23 attractive option, it has many benefits for newbie developers. You get
24 to know the code and feature set better, and learn the way GNOME
25 projects are developed. Also, you will be helping a lot of people to use
26 Anjuta better. You can use the wiki or update the manuals, DAQ, etc.
27 that are supplied with the source.
29 2. Scratch your itch. This is probably the most attractive option for a
30 reasonably experienced developer. Find something which does not work for
31 you, or some feature that you want but is missing. Then report it on the
32 devel list saying that you'd want to work on it (this is essential to
33 avoid duplication). Then send us patches !
35 3. Fixing bugs and implementing feature requests. You can find our bug
36 and RFE database at http://bugzilla.gnome.org (the module is called anjuta).
37 You can also have a look at the reasonably up-to-date TODO file we maintain
38 in the source code or view it with Task Manager in Anjuta.
40 Resources:
41 ----------
42 - Homepage: http://www.anjuta.org/
43 - Project details page: http://sourceforge.net/projects/anjuta/
44 - git: http://git.gnome.org/cgit/
45 - Anonymous CVS Access: git clone git://git.gnome.org/anjuta
46 - Mailing Lists: http://sourceforge.net/mail/?group_id=14222
47 - Bug database: http://bugzilla.gnome.org (the module is called anjuta)
48 - Feature Requests: See Bug database above
49 - Forums: http://sourceforge.net/forum/?group_id=14222
50 - IRC: irc.gnome.org (Channel: #anjuta and #devel-apps)
52 Log messages:
53 -------------
54 Log messages for git should have the following format:
56 "[Plugin/module name]: A short summary of the changes (should contain bug number)
57 (empty line)
58 [optional] A more detailed description of the changes made. Can have multiple
59 lines and should contain patch contributer, etc."
61 As an example, a typical commit against the Subversion plugin looks like this:
63     Subversion: Don't show a commit number in the info pane if no files are given
64     
65     When no files are selected, the commit isn't done and the commit number is just uninitialized junk.
67 Tools:
68 -----
69 Anjuta is written using a mixture of C and C++. You will require
70 the standard GNU tool chain and current stable GNOME libraries to 
71 build and work with the Anjuta sources.
72 New code should be in C as long as it does not touch the scintilla
73 editing component. C++ code is only allowed in the editor or if you 
74 need a library which is only availible in C++.
76 Submitting patches:
77 ------------------
78 Patches are good, and patches are always welcome! Small, self-contained 
79 patches are preferred - larger patches which touch on a large number 
80 of areas of the source tree are more complex to apply and test. 
82 Patches may be submitted to the to the mailing lists of preferable to GNOME
83 bugzilla.
85 The six-step plan to patching happiness is as follows:
86 ------------------------------------------------------
87 1) Create your patches directly using the git features -> don't write
88 patches against the tarball.
90 2) Use an up-to-date copy for the diffs
92 3) If the patch is big or is not high priority (i.e. things other than 
93 stability patches), then either send it to the lead developers directly 
94 (cc-ing them together is a nice idea), or file it at bugzilla.gnome.org. 
95 *Never* post big patches to the mailing lists, since they will annoy 
96 subscribers and are liable to be rejected by the list server. Send
97 a reference email to the list mentioning that you have sent a patch.
99 4) Include a good log message to the patch.
101 5) Name the patch with a useful filename. For example:
102  * 123456-foo-feature.patch or
103  * 987654-fixed-editor-crash
104 It's ok to include the 000x that git puts in front of the patch name
106 Coding style:
107 --------------
108 Tab size = 4, Indentation = 4, Use tabs for indentation.
109 Autoformat style: Anjuta coding style.
110 Example code:
111 <pre>
112 /* Use only C comments. Multiple line comments can be written as shown
113  * in this particular example. Avoid writting redundant and balantly
114  * obvious comments. Always put comments for tricky and hacky situations.
115  * Also notice the space before parenthesis.
116  */
117 gchar*
118 function (gchar *arg1, gint arg2, gint arg3, gpointer arg4, GHashTable *arg5,
119           gint arg7, gpointer arg7)
121     gchar *str;
122     gint x = 23; /* Only the trailing variables could be default initialized */
123     gint y = function_call (); /* This is another trailing variable decl */
124     
125     /* There should be a blank line between declarations and code */
126     if (x == y || some_long_comparision == another_long_variable ||
127         (ultra_long_function_call_that_does_not_fit_well (which_has_arguments,
128                                                           and_more_args,
129                                                           yet_more_args) &&
130          ((yet_another_conditional & ENUM_ITEM_1) == TRUE) ||
131          ((yet_another_conditional & ENUM_ITEM_2) == TRUE) ||
132          and_some_more_conditionals != MACRO_NAME) &&
133         notice_how_the_parenthesis_are_aligned_in_the_nest == TRUE)
134     {
135         switch (a)
136         {
137         case 1:
138             printf ("Hello World");
139         case 2:
140             printf ("Welcome to Anjuta");
141         default:
142             printf ("Welcome");
143         }
144     }
145     
146     /* No inline declarations of variables */
147     str = function_call (gchar *arg1, gint arg2, gint arg3, gpointer arg4,
148                          GHashTable *arg5, gint arg7, gpointer arg7,
149                          last_arg);
150     return str;
152 </pre>
154 - Try to limit the lines to 80 characters.
155 - Please try to write OO-code using GObject (or derived class) as baseclass.
156 This will lead to better design and clear module separation.
157 - If possible gnome-vfs is preferred to standard UNIX IO functions.
158 - Try to avoid forward declaration of static functions, try to keep them in 
159 order instead
160 - Use descriptive variable names like filename instead of f and cur_item instead
161 of i.
162 - If you use a "hack" please add a comment and say why this could not be done
163 cleaner.
165 General source structure:
166 ------------------------
167 When editing the code, adding new classes or methods, etc. please 
168 conform with the style already followed in the source files.
170 If a section of code will require further work, please add helpful
171 comments of the form /* FIXME: ... */, so that an external tool (such as
172 grep) can be used to identify them.
174 Separator in filename:
175 You should always use - instead of _, meaning anjuta-plugin.h
176 insted of anjuta_plugin.h
178 Key elements:
179 * libanjuta/ - Anjuta IDE framework
180 * scintilla/ - the scintilla editing component
181 * launcher/ - launcher wrapper used by the debugger
182 * tagmanager/ - the tagmanager library
183 * libegg/ - extra widgets
184 * plugins/ - plugin components (see the sample for more information)
185 * src/ - the main Anjuta IDE sources
186 * data/ - System data.
187 * mime/ - Mime related files.
188 * global-tags/ - System tags.
189 * manuals/ - All sorts of sgml documents (API and user).
191 Messages and translations:
192 -------------------------
193 There are a few rules we ask contributors to follow when adding new
194 message strings and labels to Anjuta.
196 1. BE CONSISTENT!! 
197 - refer to the standard GNOME Word List in the GNOME Style Guide 
198 (http://developer.gnome.org/documents/style-guide/) when referencing 
199 different user interface features, and then use the same terminology 
200 throughout. Try to ensure that your use of words matches the rest of
201 the code.
202 - make sure that mixed case is only used where it makes sense to do so.
204 Example: "Unable to Start Plug in Module %s".
205 This message is not ideal since the standard terminology is "plugin" (so 
206 please do not use "Plug in", "plug-in", etc.). Also, in this case there 
207 is no reason for the words "start" and "module" to start with an uppercase 
208 letter.
210 There are a few standard terms we use - in particular:
211 - plugin
212 - Project (always with an uppercase P)
214 2. Do not use contractions (don't, can't, etc.). These can make a message 
215 difficult to translate.
217 3. Do not use colloquial expressions. They may seem cool or amusing, but 
218 actually they can be hard to translate into all languages. Also, although as 
219 developers it is OK to have fun, messages with certain language in them can be 
220 intimidating for new or inexperienced users, and are not very professional.
222 Example: "You FOOL! I can not attach to myself." 
223 This message was originally used in the debugger code, and was removed some 
224 time ago. It is quite fun, but a new user might be put off. 
226 4. Do not use the first person "I" for referring to Anjuta in messages 
227 (again, the previous message is an example of this). This is bad practice in 
228 technical writing. If you need to refer to Anjuta itself, please use the word
229 "Anjuta"! :-)
231 Documentation:
232 -------------
233 The documentation is stored in the manuals/ directory, and consists 
234 of a set of SGML sources conforming to the GNOME Documentation Project's
235 Style Guide. Please ensure that all additions also follow these guidelines.
237 Screenshots used in the manual are processed using The Gimp. Single dialogs
238 and menus are converted to RGB and the Script-Fu Drop Shadow effect applied 
239 (with the default settings). All documentation images are in PNG format.
241 Translations of application messages are stored in the standard po/ 
242 directory structure at the top level of the source tree.
244 Graphics:
245 --------
246 PNG format is preferred for application graphics.
248 The image filenames are mapped in the file src/pixmaps.h, with helper functions
249 for manipulating them in src/resources.c. Please use this method for including
250 graphics and do not use the filenames directly.
252 ARCHITECTURE:
253 -------------
255 You can find the API documentation of anjuta in the 
256 "Anjuta Developers Reference Manual" devhelp book!
258 1) Event Driven:
259 ----------------
260 When Anjuta was first designed, the primary goal was to enable the use of 
261 external unix commands in a more productive and intuitive way. Therefore,
262 anjuta follows non-blocking input/output operations aggressively. This means
263 that anjuta UI will not freeze while it performs a lengthy task. All such
264 jobs are event-driven (I am not referring to the gtk-events here) and works
265 on asynchronous basis. The example jobs are compilation, debugging, file search,
266 class updates etc. While asynchronous event-driven implementation is more
267 complex than it's synchronous counter part, it gives a smooth and non frustrative
268 operation. :-)
270 For details how to use the anjuta-launcher consult AnjutaLauncher reference
271 documentation in libanjuta.
273 2) How to add new menu/toolbar items in the Main Menu:
274 ----------------------------------------------
276 Anjuta uses GtkUIManager for creating it's UI. Libanjuta does provide
277 some wrapper functions in anjuta-ui.h. Take a look at the *.xml files in the 
278 plugins, the Plugin docs in the reference and read the GtkUIManager docs for
279 details.
281 4) Dialogs and Windows:
282 -----------------------
284 Dialogs and Windows should be build using GtkBuilder. They should be HIG compliant
285 (http://developer.gnome.org/projects/gup/hig/)
287 - All dialogs should be closable by 'ESC'
288 - All dialogs should have default action.
290 Glade catalog:
291 Several Anjuta plugins, including the Subversion and Git plugins, among others,
292 use custom widgets with a Glade catalog. To be able to edit glade files for these
293 plugins, pass --enable-glade-catalog to configure to make sure that the glade
294 catalog is installed. libgladeui development files must be installed.
296 5) Property/Config management:
297 ------------------------------
299 Anjuta has a very powerful preferece management. You can read the docs of
300 AnjutaPreferences in the reference.
302 7) How to add a new project type:
303 ---------------------------------
305 FIXME: For no take a look at the project types in 
306 plugins/project-wizard/templates
308 8) Debug messages
309 ---------------------------------
311 Do not use g_message/g_warning for debug messages. Use DEBUG_PRINT instead which
312 is defined in libanjuta/anjuta-debug.h. This will assure that debug messages
313 are only presented to developers and not to normal users. Debug messages will
314 only be shown if --enable-debug is passed to configure/autogen which means that
315 DEBUG is defined.
318 9) How to correctly credit people:
319 ----------------------------------
321 New contributors must always be credited in AUTHORS file
323 You should also ensure that you submit headed ChangeLog entries with a 
324 name and e-mail address when you submit a patch.