source: calamares/trunk/fuentes/ci/HACKING.md @ 7538

Last change on this file since 7538 was 7538, checked in by kbut, 13 months ago

sync with github

File size: 6.7 KB
Line 
1Hacking on Calamares
2====================
3
4These are the guidelines for hacking on Calamares. Except for the licensing,
5which **must** be GPLv3+, these are guidelines and -- like PEP8 -- the most
6important thing is to know when you can ignore them.
7
8
9Licensing
10---------
11Calamares is released under the terms of the GNU GPL, version 3 or later.
12Every source file must have a license header, with a list of copyright holders and years.
13
14Example:
15```
16/* === This file is part of Calamares - <https://github.com/calamares> ===
17 *
18 *   Copyright 2013-2014, Random Person <name@example.com>
19 *   Copyright 2010,      Someone Else <someone@example.com>
20 *
21 *   Calamares is free software: you can redistribute it and/or modify
22 *   it under the terms of the GNU General Public License as published by
23 *   the Free Software Foundation, either version 3 of the License, or
24 *   (at your option) any later version.
25 *
26 *   Calamares is distributed in the hope that it will be useful,
27 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
28 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
29 *   GNU General Public License for more details.
30 *
31 *   You should have received a copy of the GNU General Public License
32 *   along with Calamares. If not, see <http://www.gnu.org/licenses/>.
33 */
34```
35Copyright holders must be physical or legal personalities. A statement such as
36`Copyright 2014, The FooBarQuux project` has no legal value if "The FooBarQuux
37project" is not the legal name of a person, company, incorporated
38organization, etc.
39
40Please add your name to files you touch when making any contribution (even if
41it's just a typo-fix which might not be copyrightable in all jurisdictions).
42
43
44Formatting C++
45--------------
46This formatting guide applies to C++ code only; for Python modules, we use
47[pycodestyle](https://github.com/PyCQA/pycodestyle) to apply a check of
48some PEP8 guidelines.
49
50* Spaces, not tabs.
51* Indentation is 4 spaces.
52* Lines should be limited to 90 characters.
53* Spaces between brackets and argument functions, including for template arguments
54* No space before brackets, except for keywords, for example `function( argument )` but
55  `if ( condition )`.
56* For pointer and reference variable declarations, put a space before the variable name
57  and no space between the type and the `*` or `&`, e.g. `int* p`.
58* `for`, `if`, `else`, `while` and similar statements put the braces on the next line,
59  if the following block is more than one statement. Use no braces for single statements.
60* Function and class definitions have their braces on separate lines.
61* A function implementation's return type is on its own line.
62* `CamelCase.{cpp,h}` style file names.
63
64Example:
65```
66bool
67MyClass::myMethod( QStringList list, const QString& name )
68{
69    if ( list.isEmpty() )
70        return false;
71
72    cDebug() << "Items in list ..";
73    foreach ( const QString& string, list )
74        cDebug() << "  .." << string;
75
76    switch ( m_enumValue )
77    {
78    case Something:
79        return true;
80    case SomethingElse:
81        doSomething();
82        break;
83    }
84}
85```
86
87You can use the `ci/calamaresstyle` script to run
88[astyle](http://astyle.sf.net) on your code and have it formatted the right
89way.
90
91**NOTE:** An .editorconfig file is included to assist with formatting. In
92order to take advantage of this functionality you will need to acquire the
93[EditorConfig](http://editorconfig.org/#download) plug-in for your editor.
94
95
96Naming
97------
98* Use CamelCase for everything.
99* Local variables should start out with a lowercase letter.
100* Class names are capitalized
101* Prefix class member variables with `m_`, e.g. `m_queue`.
102* Prefix static member variables with `s_`, e.g. `s_instance`.
103* Functions are named in the Qt style, like Java's, without the 'get' prefix.
104    * A getter is `variable()`.
105    * If it's a getter for a boolean, prefix with 'is', so `isCondition()`.
106    * A setter is `setVariable( arg )`.
107
108
109Includes
110--------
111Header includes should be listed in the following order:
112
113* own header,
114* Calamares includes,
115* includes for Qt-based libraries,
116* Qt includes,
117* other includes.
118
119They should also be sorted alphabetically for ease of locating them.
120
121Includes in a header file should be kept to the absolute minimum, as to keep
122compile times short. This can be achieved by using forward declarations
123instead of includes, like `class QListView;`.
124
125Example:
126```
127#include "Settings.h"
128
129#include "CalamaresApplication.h"
130#include "utils/CalamaresUtils.h"
131#include "utils/Logger.h"
132#include "YamlUtils.h"
133
134#include <QDir>
135#include <QFile>
136
137#include <yaml-cpp/yaml.h>
138```
139
140Use include guards, not `#pragma once`.
141
142
143C++ tips
144--------
145All C++11 features are acceptable, and the use of new C++11 features is encouraged when
146it makes the code easier to understand and more maintainable.
147
148The use of `nullptr` is preferred over the use of `0` or `NULL`.
149
150For Qt containers it is better to use Qt's own `foreach`. For all other containers, the
151range-based `for` syntax introduced with C++11 is preferred ([see this blog post][1]).
152
153When re-implementing a virtual method, always add the `override` keyword.
154
155Try to keep your code const correct. Declare methods const if they don't mutate the
156object, and use const variables. It improves safety, and also makes it easier to
157understand the code.
158
159For the Qt signal-slot system, the new (Qt5) syntax is to be preferred because it allows
160the compiler to check for the existence of signals and slots. As an added benefit, the
161new syntax can also be used with `tr1::bind` and C++11 lambdas. For more information, see
162the [Qt wiki][2].
163
164Example:
165```
166connect( m_next, &QPushButton::clicked, this, &ViewManager::next );
167
168connect( m_moduleManager, &Calamares::ModuleManager::modulesLoaded, [this]
169{
170    m_mainwindow->show();
171});
172```
173
174[1]: http://blog.qt.digia.com/blog/2011/05/26/cpp0x-in-qt/
175[2]: http://qt-project.org/wiki/New_Signal_Slot_Syntax
176
177
178Debugging
179---------
180Use `cDebug()` and `cLog()` from `utils/Logger.h`. You can pass a debug-level to
181either macro (1 is debugging, higher is less important). Use `cLog()` for warning
182messages. It is recommended to add *WARNING* as the first part of a warning
183message.
184
185For log messages that are continued across multiple calls to `cDebug()`,
186in particular listing things, conventional formatting is as follows:
187* End the first debug message with ` ..`
188* Indent following lines with `  ..`
189
190
191Commit Messages
192---------------
193Keep commit messages short(-ish) and try to describe what is being changed
194*as well as why*. Use the commit keywords for GitHub, especially *FIXES:*
195to auto-close issues when they are resolved.
196
197For functional changes to Calamares modules or libraries, try to put
198*[modulename]* in front of the first line of the commit message.
199
200For non-functional changes to infrastructure, try to label the change
201with the kind of change, e.g. *CMake* or *i18n* or *Documentation*.
Note: See TracBrowser for help on using the repository browser.