napcok/calamares
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation: update HACKING

Browse Source
This commit is contained in:
Adriaan de Groot 2017-11-06 06:58:05 -05:00
parent fda4b4e3c2
commit b5f2f22a78
1 changed files with 50 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
ci/HACKING.md
View File

@ -1,9 +1,15 @@
Hacking on Calamares Hacking on Calamares
==================== ====================
These are the guidelines for hacking on Calamares. Except for the licensing,
which **must** be GPLv3+, these are guidelines and -- like PEP8 -- the most
important thing is to know when you can ignore them.
Licensing Licensing
--------- ---------
Calamares is released under the terms of the GNU GPL, version 3 or later. Every source file must have a license header, with a list of copyright holders and years. Calamares is released under the terms of the GNU GPL, version 3 or later.
Every source file must have a license header, with a list of copyright holders and years.
Example: Example:
``` ```
@ -34,9 +40,9 @@ organization, etc.
Please add your name to files you touch when making any contribution (even if Please add your name to files you touch when making any contribution (even if
it's just a typo-fix which might not be copyrightable in all jurisdictions). it's just a typo-fix which might not be copyrightable in all jurisdictions).
Formatting
----------
Formatting C++
--------------
This formatting guide applies to C++ code only; for Python modules, we use This formatting guide applies to C++ code only; for Python modules, we use
[pycodestyle][https://github.com/PyCQA/pycodestyle] to apply a check of [pycodestyle][https://github.com/PyCQA/pycodestyle] to apply a check of
some PEP8 guidelines. some PEP8 guidelines.
@ -48,10 +54,10 @@ some PEP8 guidelines.
* No space before brackets, except for keywords, for example `function( argument )` but * No space before brackets, except for keywords, for example `function( argument )` but
`if ( condition )`. `if ( condition )`.
* For pointer and reference variable declarations, put a space before the variable name * For pointer and reference variable declarations, put a space before the variable name
and no space between the type and the `*` or `&`. and no space between the type and the `*` or `&`, e.g. `int* p`.
* `for`, `if`, `else`, `while` and similar statements put the brackets on the next line, * `for`, `if`, `else`, `while` and similar statements put the braces on the next line,
although brackets are not needed for single statements. if the following block is more than one statement. Use no braces for single statements.
* Function and class definitions have their brackets on separate lines. * Function and class definitions have their braces on separate lines.
* A function implementation's return type is on its own line. * A function implementation's return type is on its own line.
* `CamelCase.{cpp,h}` style file names. * `CamelCase.{cpp,h}` style file names.
@ -63,8 +69,9 @@ MyClass::myMethod( QStringList list, const QString& name )
if ( list.isEmpty() ) if ( list.isEmpty() )
return false; return false;
cDebug() << "Items in list ..";
foreach ( const QString& string, list ) foreach ( const QString& string, list )
cDebug() << "Current string is " << string; cDebug() << " .." << string;
switch ( m_enumValue ) switch ( m_enumValue )
{ {
@ -77,7 +84,7 @@ MyClass::myMethod( QStringList list, const QString& name )
} }
``` ```
You can use the `hacking/calamaresstyle` script to run You can use the `ci/calamaresstyle` script to run
[astyle](http://astyle.sf.net) on your code and have it formatted the right [astyle](http://astyle.sf.net) on your code and have it formatted the right
way. way.
@ -85,6 +92,7 @@ way.
order to take advantage of this functionality you will need to acquire the order to take advantage of this functionality you will need to acquire the
[EditorConfig](http://editorconfig.org/#download) plug-in for your editor. [EditorConfig](http://editorconfig.org/#download) plug-in for your editor.
Naming Naming
------ ------
* Use CamelCase for everything. * Use CamelCase for everything.
@ -97,6 +105,7 @@ Naming
* If it's a getter for a boolean, prefix with 'is', so `isCondition()`. * If it's a getter for a boolean, prefix with 'is', so `isCondition()`.
* A setter is `setVariable( arg )`. * A setter is `setVariable( arg )`.
Includes Includes
-------- --------
Header includes should be listed in the following order: Header includes should be listed in the following order:
@ -109,8 +118,9 @@ Header includes should be listed in the following order:
They should also be sorted alphabetically for ease of locating them. They should also be sorted alphabetically for ease of locating them.
Includes in a header file should be kept to the absolute minimum, as to keep compile times short. This can be achieved by using forward declarations instead of includes, Includes in a header file should be kept to the absolute minimum, as to keep
like `class QListView;`. compile times short. This can be achieved by using forward declarations
instead of includes, like `class QListView;`.
Example: Example:
``` ```
@ -129,6 +139,7 @@ Example:
Use include guards, not `#pragma once`. Use include guards, not `#pragma once`.
C++ tips C++ tips
-------- --------
All C++11 features are acceptable, and the use of new C++11 features is encouraged when All C++11 features are acceptable, and the use of new C++11 features is encouraged when
@ -160,10 +171,31 @@ connect( m_moduleManager, &Calamares::ModuleManager::modulesLoaded, [this]
}); });
``` ```
Debugging
---------
Use `cDebug()` and `cLog()` from `utils/Logger.h`.
[1]: http://blog.qt.digia.com/blog/2011/05/26/cpp0x-in-qt/ [1]: http://blog.qt.digia.com/blog/2011/05/26/cpp0x-in-qt/
[2]: http://qt-project.org/wiki/New_Signal_Slot_Syntax [2]: http://qt-project.org/wiki/New_Signal_Slot_Syntax
Debugging
---------
Use `cDebug()` and `cLog()` from `utils/Logger.h`. You can pass a debug-level to
either macro (1 is debugging, higher is less important). Use `cLog()` for warning
messages. It is recommended to add *WARNING* as the first part of a warning
message.
For log messages that are continued across multiple calls to `cDebug()`,
in particular listing things, conventional formatting is as follows:
* End the first debug message with ` ..`
* Indent following lines with ` ..`
Commit Messages
---------------
Keep commit messages short(-ish) and try to describe what is being changed
*as well as why*. Use the commit keywords for GitHub, especially *FIXES:*
to auto-close issues when they are resolved.
For functional changes to Calamares modules or libraries, try to put
*[modulename]* in front of the first line of the commit message.
For non-functional changes to infrastructure, try to label the change
with the kind of change, e.g. *CMake* or *i18n* or *Documentation*.