mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-14 06:42:58 +08:00
Update CONTRIBUTING.md
This commit is contained in:
Gabor Kiss-Vamosi
GitHub
parent
ee4cd4756b
commit
63c59b6570
@ -1,72 +1,68 @@
|
||||
# Contributing to Littlev Graphics Library
|
||||
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!
|
||||
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 an issue?
|
||||
## 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
|
||||
|
||||
### 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
|
||||
then tell
|
||||
* where you found the bug (which file/function/variable)
|
||||
* how can it cause problem
|
||||
* what is your suggeseted solution if you have
|
||||
|
||||
### Complex issue
|
||||
If you find a complex issue which:
|
||||
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)
|
||||
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)
|
||||
|
||||
### Abbreviations
|
||||
Please read this document to see the list of accepted abbreviations: [abbreviations-in-code](https://github.com/kisvegabor/abbreviations-in-code)
|
||||
### 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
|
||||
|
||||
### 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*
|
||||
### 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.
|
||||
*/
|
||||
void lv_label_set_text(lv_obj_t * label, const char * text)
|
||||
{ /*Main bracket in new line*/
|
||||
{ /* Main bracket of functions in new line*/
|
||||
|
||||
if(label == NULL) return; /*No bracket only if the command is inline with the if statement*/
|
||||
|
||||
@ -172,14 +148,12 @@ void lv_label_set_text(lv_obj_t * label, const char * text)
|
||||
lv_label_ext_t * ext = lv_obj_get_ext(label);
|
||||
|
||||
/*Comment before a section */
|
||||
if(text == ext->txt || text == NULL) { /*Bracket start inline*/
|
||||
if(text == ext->txt || text == NULL) { /*Bracket of statements start inline*/
|
||||
lv_label_refr_text(label);
|
||||
return;
|
||||
}
|
||||
|
||||
.
|
||||
.
|
||||
.
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user