mirror of
https://github.com/lvgl/lvgl.git
synced 2026-05-29 06:36:05 +08:00
create docs folder and move documents there
This commit is contained in:
Kiss-Vamosi Gabor
@@ -0,0 +1,172 @@
|
||||
# Contributing to Littlev Graphics Library
|
||||
First of all thank you for reading these guide before contributing!
|
||||
|
||||
In this guid you can read how can you help in developing the Littlev Graphic Library. These are not strick rules reather just suggestions. If you have a constructive idea just create pull request on this document!
|
||||
|
||||
### 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 suggest a feature?](#how-to-suggest-a-feature)
|
||||
* [Styling guide](#styling-guide)
|
||||
* [Git Commit Messages](#Git-mommit-messages)
|
||||
* [File format](#file-format)
|
||||
* [Function](#functions)
|
||||
* [Variables](#variables)
|
||||
* [Defines](#define)
|
||||
* [Comments](#comments)
|
||||
* [Formatting](#formatting)
|
||||
|
||||
|
||||
## Who can contribute?
|
||||
Basically everybody is welcome in contributing independently from skills, programming level or any personal attribute.
|
||||
|
||||
There are several ways to contribute in the graphics library like:
|
||||
* Report an issue
|
||||
* Suggest feature
|
||||
* Fix an issue
|
||||
* Implement a feature
|
||||
|
||||
Please, take a look at [CODE_OF_CONDUCT](https://github.com/littlevgl/lvgl/blob/master/CODE_OF_CONDUCT.md)
|
||||
|
||||
## 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.
|
||||
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 becuse 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:
|
||||
* 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)
|
||||
|
||||
## 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:
|
||||
* What the new feature is about?
|
||||
* Why/Where/In which case is it useful/helpful/relevant?
|
||||
* 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.
|
||||
|
||||
The new feature should be in a new branch.
|
||||
|
||||
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)
|
||||
|
||||
## Styling guide
|
||||
|
||||
### Git Commit Messages
|
||||
* Use the present tense ("Add feature" not "Added feature")
|
||||
* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
|
||||
* Limit the first line to 72 characters or less
|
||||
* Reference issues and pull requests liberally after the first line
|
||||
|
||||
### 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)
|
||||
|
||||
### Function
|
||||
* try to write function shorter then is 40 lines
|
||||
* always shorter then 100 lines (except very straightforwards)
|
||||
* in function names:
|
||||
* words sperated 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 sperated 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*
|
||||
|
||||
### Comments
|
||||
Before every function have a comment like this:
|
||||
|
||||
```
|
||||
/**
|
||||
* Return with the screen of an object
|
||||
* @param obj pointer to an object
|
||||
* @return pointer to a screen
|
||||
*/
|
||||
lv_obj_t * lv_obj_get_scr(lv_obj_t * obj);
|
||||
```
|
||||
|
||||
Always use `/* Something */` format and NOT `//Something`
|
||||
|
||||
Write readable code to avoid descriptive comments like:
|
||||
`x++; /* Add 1 to x */`.
|
||||
The code should show clearly what you are doing.
|
||||
|
||||
You should write **why** have you done this:
|
||||
`x++; /*Because of closeing '\0' of the string */`
|
||||
|
||||
### Formatting
|
||||
Here is example to show bracket placing and using of white spaces:
|
||||
```
|
||||
/**
|
||||
* Set a new text for a label. Memory will be allocated to store the text by the label.
|
||||
* @param label pointer to a label object
|
||||
* @param text '\0' terminated character string. NULL to refresh with the current text.
|
||||
*/
|
||||
void lv_label_set_text(lv_obj_t * label, const char * text)
|
||||
{ /*Main bracket in new line*/
|
||||
|
||||
if(label == NULL) return; /*No bracket only if the command is inline with the if statement*/
|
||||
|
||||
lv_obj_inv(label);
|
||||
|
||||
lv_label_ext_t * ext = lv_obj_get_ext(label);
|
||||
|
||||
/*Comment before a section */
|
||||
if(text == ext->txt || text == NULL) { /*Bracket start inline*/
|
||||
lv_label_refr_text(label);
|
||||
return;
|
||||
}
|
||||
|
||||
.
|
||||
.
|
||||
.
|
||||
}
|
||||
```
|
||||
|
||||
Use 4 spaces indentation instead of tab.
|
||||
Reference in New Issue
Block a user