1Contribution Guidelines
  2=======================
  3
  4In order to contribute to mGBA, there are a few things to be mindful of so as to ease the process.
  5
  6Filing issues
  7-------------
  8New issues should be filed on the [mGBA GitHub Issues tracker](http://mgba.io/i/). When filing issues, please include the following information:
  9
 10* The build you are using. For recent builds, this is visible in the title bar. For example, `0.3-2134-4ec19aa`. On older builds, such as 0.2.1, this is not present, so please specify the version you downloaded or built. If present, this contains the version, branch name (if not `master`), a revision number and a truncated revision hash. For this example, it means that it's version 0.3, on `master`, commit number 2134 and revision hash `4ec19aa`. Additionally, `-dirty` will be appended if there are local changes that haven't been commited.
 11* The operating system you're using, for example Windows 7 32-bit or Ubuntu 15.04 64-bit.
 12* Your CPU and graphics card (usually not necessary). For example, Core i5-3570K and AMD Radeon R9 280X.
 13
 14Please also describe the issue in as much detail as possible, including the name of the games you have reproduced the issue on, and how you managed to enter the buggy state. If applicable, savestates can be renamed to be .png files and attached to the issue directly.
 15
 16Filing pull requests
 17--------------------
 18When filing a pull request, please make sure you adhere to the coding style as outlined below, and are aware of the requirements for licensing. Furthermore, please make sure all commits in the pull request have coherent commit messages as well as the name of the component being modified in the commit message.
 19
 20Some components are as follows:
 21
 22* ARM7: The ARM core
 23* GBA: GBA code
 24	* GBA Memory: Memory-specific
 25	* GBA Video: Video, rendering
 26	* GBA Audio: Audio processing
 27	* GBA SIO: Serial I/O, multiplayer, link
 28	* GBA Hardware: Extra devices, e.g. gyro, light sensor
 29	* GBA RR: Rerecording features
 30	* GBA Thread: Thread-layer abstractions
 31	* GBA BIOS: High-level BIOS
 32* Qt: Qt port-related code
 33* SDL: SDL port-related code (including as used in other ports)
 34* Video: Video recording code
 35* Util: Common utility code
 36* Tools: Miscellaneous tools
 37* Debugger: Included debugging functionality
 38* All: Changes that don't touch specific components but affect the project overall
 39
 40
 41Coding Style
 42------------
 43mGBA aims to have a consistent, clean codebase, so when contributing code to mGBA, please adhere to the following rules. If a pull request has style errors, you will be asked to fix them before the PR will be accepted.
 44
 45### Naming
 46
 47Variable names, including parameters, should all be in camelCase. File-scoped static variables must start with an underscore.
 48
 49C struct names should start with a capital letter, and functions relating to these structs should start with the name of the class (including the capital letter) and be in camelCase after. C struct should not be `typedef`ed.
 50
 51Functions not associated with structs should be in camelCase throughout. Static functions not associated with structs must start with an underscore.
 52
 53Enum values and `#define`s should be all caps with underscores.
 54
 55Good:
 56
 57	static int _localVariable;
 58	
 59	struct LocalStruct {
 60		void (*methodName)(struct LocalStruct struct, param);
 61		
 62		int memberName;
 63	};
 64	
 65	enum {
 66		ENUM_ITEM_1,
 67		ENUM_ITEM_2
 68	};
 69	
 70	void LocalStructCreate(struct LocalStruct* struct);
 71	
 72	void functionName(int argument);
 73
 74	static void _LocalStructUse(struct LocalStruct* struct);
 75	static void _function2(int argument2);
 76
 77C++ classes should be confined to namespaces. For the Qt port, this namespace is called `QGBA`.
 78
 79Class names should be handled similarly to C structs. Fields should be prefixed according to their scoping:
 80
 81* `m_` for non-static member.
 82* `s_` for static member.
 83
 84### Braces
 85
 86Braces do not go on their own lines, apart from the terminating brace. There should be a single space between the condition clause and the brace. Furthermore, braces must be used even for single-line blocks.
 87
 88Good:
 89
 90	if (condition) {
 91		block;
 92	} else if (condition2) {
 93		block2;
 94	} else {
 95		block3;
 96	}
 97
 98Bad (separate line):
 99
100	if (condition)
101	{
102		block;
103	}
104	else if (condition2)
105	{
106		block2;
107	}
108	else
109	{
110		block3;
111	}
112
113Bad (missing braces):
114
115	if (condition)
116		statement;
117	else if (condition2)
118		statement2;
119	else
120		statement3;
121
122Bad (missing space):
123
124	if (condition){
125		block;
126	}
127	
128### Spacing
129
130Indentation should be done using tabs and should match the level of braces. Alignment within a line should be done sparingly, but only done with spaces.
131
132### Header guards
133
134For C headers guards, the define should be the filename (including H), all-caps, with underscores instead of punctuation.
135
136Good:
137
138	#ifndef FILE_NAME_H
139	#define FILE_NAME_H
140	
141	// Header
142	
143	#endif
144
145There should be no comment on the `#endif`.
146
147For Qt (C++ header guards), the define should start with `QGBA_` and not include `_H`, but is otherwise the same. This is mostly for legacy reasons., and may change in the future.
148
149Good:
150
151	#ifndef QGBA_FILE_NAME
152	#define QGBA_FILE_NAME
153	
154	// Header
155	
156	#endif
157
158### Other
159
160Block statements such as `if`, `while` and `for` should have a space between the type of block and the parenthesis.
161
162Good:
163
164	while (condition) {
165		block;
166	}
167
168Bad:
169
170	while(condition) {
171		block;
172	}
173
174In C code, use `0` instead of `NULL`. This is mostly for legacy reasons and may change in the future. C code should also use `bool` types and values `true` and `false` instead of `1` and `0` where applicable. In C++ code, use `nullptr` instead of `NULL` or `0`.
175
176If a statement has no body, putting braces is not required, and a semicolon can be used. This is not required, but is suggested.
177
178Good:
179
180	while (f());
181
182Bad:
183
184	while (f()) {}
185
186
187For infinite loops that `break` statements internally, `while (true)` is preferred over `for (;;)`.
188
189Licensing
190---------
191
192mGBA is licensed under the [Mozilla Public License version 2.0](https://www.mozilla.org/MPL/2.0/). This entails a few things when it comes to adding code to mGBA.
193
194* New code to mGBA will be licensed under the MPL 2.0 license.
195* GPL-licensed code cannot be added to mGBA upstream, but can be linked with mGBA when compiled.
196* MIT, BSD, CC0, etc., code can be added to mGBA upstream, but preferably in the `third-party` section if applicable.