First of all thank you for reading these guide before contributing!
It's glad to see that you are interested in Contributing to LittlevGL!
In this guide you can read how can you help in developing the Littlev Graphic Library. If you have a constructive idea just create pull request on this document!
In this guide you can learn how can you help to develop LittlevGL.
### Table Of Content
*[Who can contribute?](#who-can-contribute)
*[How to report an issue?](#how-to-report-an-issue)
*[Simple issue](#simple-issue)
*[Complex issue](#complex-issue)
*[How to report an issue?](#how-to-report-a-bug)
*[How to suggest a feature?](#how-to-suggest-a-feature)
*[How to implement a feature?](#how-to-implement-a-feature)
*[Styling guide](#styling-guide)
*[File format](#file-format)
*[Functions](#functions)
*[Variables](#variables)
*[Defines](#defines)
*[Typedefs](#typedefs)
*[Comments](#comments)
*[Formatting](#formatting)
## Who can contribute?
As graphical interfaces for embedded systems has an increasing relevance today. You also might find important to work with a good graphics library. Now - independently from skills, programming level or any personal attributes - you can influence the development of the graphics library with:
As graphical interfaces for embedded systems has an increasing relevance today you also might find important to work with a good graphics library. Now - independently from skills, programming level or any personal attributes - you can influence and help the development of Littlev Graphics Library with:
* Report an issue
* Suggest feature
* Fix an issue
* Implement a feature
* Help with testing bugfixes and new features
Please, take a look at [CODE_OF_CONDUCT](https://github.com/littlevgl/lvgl/blob/master/docs/CODE_OF_CONDUCT.md)
Continue reading to know how you can be part of the development! We are waiting for you!
## How to report an issue?
### Simple issue
If you find an issue which is very simple to fix, and you fixed it, please send a pull request against `beta` branch.
A simple issue could be:
* Misspelled names
* Comment: misspelling or grammatical error in comments
* Variable: misspelled variable name (e.g. ***ojb**_next* instead of ***obj**_next*)
* Define: only local defines in files because global defines affect API
* Function: only static function name because global functions affect API
* Not handled error case:
* A parameter can be NULL (during normal usage)
* Negative index in array or over indexing
* Overflow in variable
* Anything which is local an can be fixed with a few lines of code
### Complex issue
If you find a complex issue which:
There a few general rules:
* We use [GitHub's issue tracker](https://github.com/littlevgl/lvgl/issues)
* Be kind and respectful. Strating with "Hi" is always a good idea :)
* If somebedy helped you give a feedback.
* Always create an issue before creating a [Pull request](https://help.github.com/articles/about-pull-requests/)(maybe somebeody already working on this issue)
* One issue should be about one topic. If you have other questions please open a new issue.
* Tell your remarks in a structured way. Use paragraphs and the [Markdown](https://guides.github.com/features/mastering-markdown/) support of GitHub.
* Be sure you are using the lates version (from `master` branch)
## How to report a bug?
If you found a **simple and straightforward bug** like:
* misspelling (in comments function/variable names or grammatical issues in comments)
* not handled error cases (negative array index, overflow etc)
* anything else which can be fixed locally with a few lines of code
* or defective documentation
then tell
* where you found the bug (which file/function/variable)
* how can it cause problem
* what is your suggeseted solution if you have
If you faced with **something more clomplex** like:
* might be simple but you don't know its origin
* affects a whole file, module or even the architecture
* needs deeper discussion
please create a **new issue** and describe
* what you experience
* how to reproduce the issue (maybe with example code)
* version you are using (lvgl.h)
* misc library version (misc.h)
then please tell
* what do you experience
* what do you expect to happen
* how to reproduce the issue (maybe with an example code)
## How to suggest a feature?
If you have a good and useful idea you can use GitHub issues to suggest a new feature. Please note the followings on feature requests:
If you have a good and useful idea open issue to tell it! Please note the followings on suggesting new features:
* What the new feature is about?
* Why/Where/In which case is it useful/helpful/relevant?
* Can you mention real life usecases/examples for the use this feature?
* Can you help in implementing it?
After a discussion we figure out the specification of the new feature and the technical details/implementation possibilities.
With the knowledge of how to do it somebody can implement the new feature.
Your suggestion can have 4 possible outcomes:
1. This feature is already exists. In this case you will learn how to achive your goal.
2. You can simply realize it with the current functionality.
3. Although it's a new feature but it would break LittlevGL's platform independent and/or resource minimalist nature.
4. It's really a new feature which would be good to be in LittlevGL. Hurray! In a discussion we figure out the technical details andimplementation options. With the knowledge of how to do it somebody can implement the new feature.
Keep in mind if you wouldn't like to do the implementation there is no guarantee that it will be ready in the new future.
However if you would like to force it, take a look at this page: [Feature request service](http://www.gl.littlev.hu/services#feature)
...
...
@@ -79,55 +75,35 @@ The new feature should be in a new branch.
## Styling guide
### File format
Use [misc/templ/templ.c](https://github.com/littlevgl/misc/blob/master/templ/templ.c) and [misc/templ/templ.h](https://github.com/littlevgl/misc/blob/master/templ/templ.h)
### Abbreviations
Please read this document to see the list of accepted abbreviations: [abbreviations-in-code](https://github.com/kisvegabor/abbreviations-in-code)
### Functions
* try to write function shorter then is 40 lines
* always shorter then 100 lines (except very straightforwards)
* in function names:
* words sparated by '_'
* only lower case letters
* only clear abbreviation (OK: *lv_xy_get_title_txt*, BAD: *lv_xy_get_ttxt*)
#### Global functions names (API)
An example: *lv_btn_set_state()*
* starts with *lv*
* followed by module name: *btn*, *label*, *style* etc.
* followed by the action: *set*, *get*, *refr* etc.
* closed with subject: *name*, *size*, *state* etc.
* optional like in *lv_obj_del()* it is missing
* could contain more words: *long_mode*, *point_all*
#### Static functions names
Names can be used freely.
### Variables
* words sparated by '_'
* always lower case
* one line, one declaration (BAD: char x, y;)
* use `<stdint.h>` (*uint8_t*, *int32_t* etc)
* declare variables when needed (not all at function start)
* use the smallest required scope
* variables in a file (outside functions) are always *static*
* do not use global variables (use functions to set/get static variables)
### Defines
* always upper case
* starts with *LV_*
* followed by the modul: *OBJ*, *BTN* etc.
* closed by the subject: *ANIM_TIME*, *VALUE_MIN*, *WIDTH_DEF*
### Typedefs
- prefer `typedef struct` instead of `struct name`
- prefer `typedef enum` instead of `enum name`
- types always lowercase speperated by '_'
- first word for public typedefs is *lv_...*
- next word identifies the modul: *lv_obj_...*, *lv_btn_...*
- always add closing *..._t*
- Examples: *lv_obj_t*, *lv_cont_layout_t*
Use [lv_misc/lv_templ.c](https://github.com/littlevgl/lvgl/blob/master/lv_misc/lv_templ.c) and [lv_misc/lv_templ.h](https://github.com/littlevgl/lvgl/blob/master/lv_misc/lv_templ.h)
### Naming conventions
* Words are sparated by '_'
* In variable and function names use only lower case letters (e.g. *height_tmp*)
* In enums and defines use only upper case letters (e.g. *e.g. MAX_LINE_NUM*)
* Global names (API):
* starts with *lv*
* followed by module name: *btn*, *label*, *style* etc.
* followed by the action (for functions): *set*, *get*, *refr* etc.
* closed with the subject: *name*, *size*, *state* etc.
* Typedefs
* prefer `typedef struct` and `typedef enum` instead of `struct name` and `enum name`
* always add a closing *..._t*
* Abbreviations:
* Use abbreviations on public names only if they become longer then 32 characters
* Use only very straightforward (e.g. pos: position) or well established (e.g. pr: press) abbreviatons
### Coding guide
* Functions:
* Try to write function shorter then is 50 lines
* Always shorter then 100 lines (except very straightforwards)
* Variables:
* One line, one declaration (BAD: char x, y;)
* Use `<stdint.h>` (*uint8_t*, *int32_t* etc)
* Declare variables when needed (not all at function start)
* Use the smallest required scope
* Variables in a file (outside functions) are always *static*
* Do not use global variables (use functions to set/get static variables)
### Comments
Before every function have a comment like this:
...
...
@@ -152,7 +128,7 @@ You should write **why** have you done this:
Short "code summaries" of a few lines are accepted. E.g. `/*Calculate the new coordinates*/`
In comments use `' '` when refering to a variable. E.g. `/*Update the value of 'x_act'*/`
In comments use \`\` when refering to a variable. E.g. ``/*Update the value of `x_act`*/``
### Formatting
Here is example to show bracket placing and using of white spaces:
...
...
@@ -163,7 +139,7 @@ Here is example to show bracket placing and using of white spaces:
* @param text '\0' terminated character string. NULL to refresh with the current text.
