[pulseview.git] / HACKING

-------------------------------------------------------------------------------
HACKING
-------------------------------------------------------------------------------

Coding style
------------

This project is programmed using the Linux kernel coding style:

  https://www.kernel.org/doc/html/latest/process/coding-style.html

Please use the same style for any code contributions, thanks!

In some exceptional cases deviations from the above coding guidelines are
OK (in order to meet Qt/C++ related guidelines, for example).


Contributions
-------------

 - Patches should be sent to the development mailinglist at
   sigrok-devel@lists.sourceforge.net (please subscribe to the list first).

   https://lists.sourceforge.net/lists/listinfo/sigrok-devel

 - Alternatively, you can also clone the git repository and let us know
   from where to pull/review your changes. You can use gitorious.org,
   github.com, or any other public git hosting site.


Random notes
------------

 - Consistently use g_try_malloc() / g_try_malloc0(). Do not use standard
   malloc()/calloc() if it can be avoided (sometimes other libs such
   as libftdi can return malloc()'d memory, for example).

 - Always properly match allocations with the proper *free() functions. If
   glib's g_try_malloc()/g_try_malloc0() was used, use g_free() to free the
   memory. Otherwise use standard free(). Never use the wrong function!

 - Never use g_malloc() or g_malloc0(). These functions do not return nullptr
   if not enough memory is available but rather lead to an exit() or segfault
   instead. This behaviour is not acceptable.
   Use g_try_malloc()/g_try_malloc0() instead and check the return value.

 - Use glib's gboolean / TRUE / FALSE for boolean types consistently.
   Do not use <stdbool.h> and its true / false, and do not invent private
   definitions for this either.

 - Consistently use the same naming convention for #include guards in headers:
   <PROJECTNAME>_<PATH_TO_FILE>_<FILE>
   This ensures that all #include guards are always unique and consistent.
   Example: PULSEVIEW_PV_VIEW_RULER_H

 - Consistently use the same naming convention for functions, if appropriate:

   Getter/setter function names should usually end with "_get" or "_set".
   Functions creating new "objects" should end with "_new".
   Functions destroying "objects" should end with "_destroy".
   Functions adding or removing items (e.g. from lists) should end with
   either "_add" or "_remove".
   Functions operating on all items from a list (not on only one of them),
   should end with "_all", e.g. "_remove_all", "_get_all", and so on.
   Use "_remove_all" in favor of "_clear" for consistency.

 - In Doxygen comments, put an empty line between the block of @param lines
   and the final @return line. The @param lines themselves (if there is more
   than one) are not separated by empty lines.

 - Use QIcon::fromTheme() for icons that are included in the freedesktop.org
   icon naming specification. Do NOT use it for all other icons.


Release engineering
-------------------

See

 http://sigrok.org/wiki/Developers/Release_process

for a list of items that need to be done when releasing a new tarball.
Commit	Line	Data
	1	-------------------------------------------------------------------------------
	2	HACKING
	3	-------------------------------------------------------------------------------
	4
	5	Coding style
	6	------------
	7
	8	This project is programmed using the Linux kernel coding style:
	9
	10	https://www.kernel.org/doc/html/latest/process/coding-style.html
	11
	12	Please use the same style for any code contributions, thanks!
	13
	14	In some exceptional cases deviations from the above coding guidelines are
	15	OK (in order to meet Qt/C++ related guidelines, for example).
	16
	17
	18	Contributions
	19	-------------
	20
	21	- Patches should be sent to the development mailinglist at
	22	sigrok-devel@lists.sourceforge.net (please subscribe to the list first).
	23
	24	https://lists.sourceforge.net/lists/listinfo/sigrok-devel
	25
	26	- Alternatively, you can also clone the git repository and let us know
	27	from where to pull/review your changes. You can use gitorious.org,
	28	github.com, or any other public git hosting site.
	29
	30
	31	Random notes
	32	------------
	33
	34	- Consistently use g_try_malloc() / g_try_malloc0(). Do not use standard
	35	malloc()/calloc() if it can be avoided (sometimes other libs such
	36	as libftdi can return malloc()'d memory, for example).
	37
	38	- Always properly match allocations with the proper *free() functions. If
	39	glib's g_try_malloc()/g_try_malloc0() was used, use g_free() to free the
	40	memory. Otherwise use standard free(). Never use the wrong function!
	41
	42	- Never use g_malloc() or g_malloc0(). These functions do not return nullptr
	43	if not enough memory is available but rather lead to an exit() or segfault
	44	instead. This behaviour is not acceptable.
	45	Use g_try_malloc()/g_try_malloc0() instead and check the return value.
	46
	47	- Use glib's gboolean / TRUE / FALSE for boolean types consistently.
	48	Do not use <stdbool.h> and its true / false, and do not invent private
	49	definitions for this either.
	50
	51	- Consistently use the same naming convention for #include guards in headers:
	52	<PROJECTNAME>_<PATH_TO_FILE>_<FILE>
	53	This ensures that all #include guards are always unique and consistent.
	54	Example: PULSEVIEW_PV_VIEW_RULER_H
	55
	56	- Consistently use the same naming convention for functions, if appropriate:
	57
	58	Getter/setter function names should usually end with "_get" or "_set".
	59	Functions creating new "objects" should end with "_new".
	60	Functions destroying "objects" should end with "_destroy".
	61	Functions adding or removing items (e.g. from lists) should end with
	62	either "_add" or "_remove".
	63	Functions operating on all items from a list (not on only one of them),
	64	should end with "_all", e.g. "_remove_all", "_get_all", and so on.
	65	Use "_remove_all" in favor of "_clear" for consistency.
	66
	67	- In Doxygen comments, put an empty line between the block of @param lines
	68	and the final @return line. The @param lines themselves (if there is more
	69	than one) are not separated by empty lines.
	70
	71	- Use QIcon::fromTheme() for icons that are included in the freedesktop.org
	72	icon naming specification. Do NOT use it for all other icons.
	73
	74
	75	Release engineering
	76	-------------------
	77
	78	See
	79
	80	http://sigrok.org/wiki/Developers/Release_process
	81
	82	for a list of items that need to be done when releasing a new tarball.
	83