[andy/viking.git] / HACKING

This file is meant to summarize the Viking development policies.

####
#### Also check information in the Wiki:
#### http://sourceforge.net/apps/mediawiki/viking/index.php?title=Main_Page
####

Clean commits
=============

Commits/patches should be as fine-grained as possible (and no finer). Every
distinct change should be in its own commit and every commit should be a
meaningful change on its own.

Preferred Code Contribution Methods
===================================

Since the project uses git for source control, patches that utilize git (especially for patch sets) are preferred in this order:
* Commits pushed to a publically accessible git host (e.g. GitHub, Gitorious, etc...)
   - This enables commits to be easily managed such as pulling, merging or cherry-picking
* Email git diffs to the dev mailing list - use 'git format-patch' method
* Plain diffs can be emailed to the dev mailing list and/or stored in the SourceForge Patch Tracker for Viking.

Coding style
============

Naming:
A "module" is a .c file.

Functions starting with "vik_" operate on an object/structure with the
module name (see layer.c for an example).  Functions starting with
"a_" do not, these modules may have static variables.  Both are
followed by the module name. Unless of course the function is static,
in which case it may be called anything.

All (well, practically all) global constants and macros start with
"VIK_" and then the module name.

Coding Checks
=============

Code should compile with the minimum number of warnings (ideally none).

Code should pass static analysis with defaults for 'cppcheck' (http://sourceforge.net/projects/cppcheck/) with no errors.

ATM there is one deliberate error in vikgpslayer.c designed to prevent building if the code encounters a GPSD version we don't handle. Something like:
[vikgpslayer.c:1479]: (error) Invalid number of character ({) when these macros are defined: 'GPSD_API_MAJOR_VERSION;VIK_CONFIG_REALTIME_GPS_TRACKING'.
This can be 'hidden' via cppcheck --suppress syntax.

Technical notices
=================

In order to activate reference documentation, you have to specify the
following configure command line:
$ ./configure --enable-gtk-doc --enable-gtk-doc-html

Then, cd to doc/reference and launch make command.

---

The layers panel holds all the layers. Layers connect to the layers
panel via what I call "interfaces" which are really just a structure
of function pointers and pointers to other bits such as
icons. viklayer.c switches between the layers like
polymorhpism. Anything specific to the layer should (in theory) be
found solely in that layer's source file.

There are some ugly hacks in here, like the layers panel holding the
viewport and each layer holding the viewport and a
GtkTreeIter. Unfortunately it was the only way I could figure out to
do some things. It would be _much_ easier with a object-oriented
language.

---

"xmpp" and "ympp" are really misnomers, as they only represent the
Meters Per Pixel in UTM mode. Otherwise they are an artificial zooming
system. In expedia mode it represents the "Alti", in Google mode it
represents 2^(scale), e.g. 2^0 = 1, 2^8 = 256.

---
Implementing a MapSource

VikMapSource is the "interface", the really base class of the
MapSource tree.  In order to implement a MapSource, you have to prefer
to derive from VikMapSourceDefault, a less abstract class, adding a
property based implementation for some aspects of the VikMapSource
interface.  Then, you have to provide implementation for
coord_to_mapcoord, mapcoord_to_center_coord and download methods.
Commit	Line	Data
240d1fc8 GB	1	This file is meant to summarize the Viking development policies.
240d1fc8 GB	2
6c1496fc RN	3	####
	4	#### Also check information in the Wiki:
	5	#### http://sourceforge.net/apps/mediawiki/viking/index.php?title=Main_Page
	6	####
240d1fc8 GB	7
	8	Clean commits
	9	=============
	10
	11	Commits/patches should be as fine-grained as possible (and no finer). Every
	12	distinct change should be in its own commit and every commit should be a
	13	meaningful change on its own.
	14
6c1496fc RN	15	Preferred Code Contribution Methods
	16	===================================
	17
	18	Since the project uses git for source control, patches that utilize git (especially for patch sets) are preferred in this order:
	19	* Commits pushed to a publically accessible git host (e.g. GitHub, Gitorious, etc...)
	20	- This enables commits to be easily managed such as pulling, merging or cherry-picking
	21	* Email git diffs to the dev mailing list - use 'git format-patch' method
	22	* Plain diffs can be emailed to the dev mailing list and/or stored in the SourceForge Patch Tracker for Viking.
	23
240d1fc8 GB	24	Coding style
	25	============
	26
50a14534 EB	27	Naming:
	28	A "module" is a .c file.
	29
c85a3d4b GT	30	Functions starting with "vik_" operate on an object/structure with the
	31	module name (see layer.c for an example). Functions starting with
	32	"a_" do not, these modules may have static variables. Both are
	33	followed by the module name. Unless of course the function is static,
	34	in which case it may be called anything.
50a14534	35
c85a3d4b GT	36	All (well, practically all) global constants and macros start with
c85a3d4b GT	37	"VIK_" and then the module name.
50a14534	38
6c1496fc RN	39	Coding Checks
	40	=============
	41
	42	Code should compile with the minimum number of warnings (ideally none).
	43
	44	Code should pass static analysis with defaults for 'cppcheck' (http://sourceforge.net/projects/cppcheck/) with no errors.
	45
	46	ATM there is one deliberate error in vikgpslayer.c designed to prevent building if the code encounters a GPSD version we don't handle. Something like:
	47	[vikgpslayer.c:1479]: (error) Invalid number of character ({) when these macros are defined: 'GPSD_API_MAJOR_VERSION;VIK_CONFIG_REALTIME_GPS_TRACKING'.
	48	This can be 'hidden' via cppcheck --suppress syntax.
	49
240d1fc8 GB	50	Technical notices
240d1fc8 GB	51	=================
50a14534	52
c85a3d4b GT	53	In order to activate reference documentation, you have to specify the
c85a3d4b GT	54	following configure command line:
e5c58469 GB	55	$ ./configure --enable-gtk-doc --enable-gtk-doc-html
	56
	57	Then, cd to doc/reference and launch make command.
	58
	59	---
	60
c85a3d4b GT	61	The layers panel holds all the layers. Layers connect to the layers
	62	panel via what I call "interfaces" which are really just a structure
	63	of function pointers and pointers to other bits such as
	64	icons. viklayer.c switches between the layers like
	65	polymorhpism. Anything specific to the layer should (in theory) be
	66	found solely in that layer's source file.
50a14534	67
c85a3d4b GT	68	There are some ugly hacks in here, like the layers panel holding the
	69	viewport and each layer holding the viewport and a
	70	GtkTreeIter. Unfortunately it was the only way I could figure out to
	71	do some things. It would be _much_ easier with a object-oriented
	72	language.
50a14534 EB	73
	74	---
	75
c85a3d4b GT	76	"xmpp" and "ympp" are really misnomers, as they only represent the
	77	Meters Per Pixel in UTM mode. Otherwise they are an artificial zooming
	78	system. In expedia mode it represents the "Alti", in Google mode it
	79	represents 2^(scale), e.g. 2^0 = 1, 2^8 = 256.
2a035b62 GB	80
	81	---
	82	Implementing a MapSource
	83
c85a3d4b GT	84	VikMapSource is the "interface", the really base class of the
	85	MapSource tree. In order to implement a MapSource, you have to prefer
	86	to derive from VikMapSourceDefault, a less abstract class, adding a
	87	property based implementation for some aspects of the VikMapSource
	88	interface. Then, you have to provide implementation for
	89	coord_to_mapcoord, mapcoord_to_center_coord and download methods.