acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

CONTRIBUTING.md (16077B)

      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/CONTRIBUTING.md
      4 ```
      5 
      6 # Contributing
      7 
      8 ## Introduction
      9 
     10 Join LVGL's community and leave your footprint in the library!
     11 
     12 There are a lot of ways to contribute to LVGL even if you are new to the library or even new to programming.
     13 
     14 It might be scary to make the first step but you have nothing to be afraid of.
     15 A friendly and helpful community is waiting for you. Get to know like-minded people and make something great together.
     16 
     17 So let's find which contribution option fits you the best and help you join the development of LVGL!
     18 
     19 Before getting started here are some guidelines to make contribution smoother:
     20 - Be kind and friendly.
     21 - Be sure to read the relevant part of the documentation before posting a question.
     22 - Ask questions in the [Forum](https://forum.lvgl.io/) and use [GitHub](https://github.com/lvgl/) for development-related discussions.
     23 - Always fill out the post or issue templates in the Forum or GitHub (or at least provide equivalent information). It makes understanding your contribution or issue easier and you will get a useful response faster.
     24 - If possible send an absolute minimal but buildable code example in order to reproduce the issue. Be sure it contains all the required variable declarations, constants, and assets (images, fonts).
     25 - Use [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to format your posts. You can learn it in 10 minutes.
     26 - Speak about one thing in one issue or topic. It makes your post easier to find later for someone with the same question.
     27 - Give feedback and close the issue or mark the topic as solved if your question is answered.
     28 - For non-trivial fixes and features, it's better to open an issue first to discuss the details instead of sending a pull request directly.
     29 - Please read and follow the <a href="https://github.com/lvgl/lvgl/blob/master/docs/CODING_STYLE.md">Coding style</a> guide.
     30 
     31 ## Pull request
     32 
     33 Merging new code into the lvgl, documentation, blog, examples, and other repositories happen via *Pull requests* (PR for short).
     34 A PR is a notification like "Hey, I made some updates to your project. Here are the changes, you can add them if you want."
     35 To do this you need a copy (called fork) of the original project under your account, make some changes there, and notify the original repository about your updates.
     36 You can see what it looks like on GitHub for LVGL here: [https://github.com/lvgl/lvgl/pulls](https://github.com/lvgl/lvgl/pulls).
     37 
     38 To add your changes you can edit files online on GitHub and send a new Pull request from there (recommended for small changes) or
     39  add the updates in your favorite editor/IDE and use git to publish the changes (recommended for more complex updates).
     40 
     41 ### From GitHub
     42 1. Navigate to the file you want to edit.
     43 2. Click the Edit button in the top right-hand corner.
     44 3. Add your changes to the file.
     45 4. Add a commit message on the bottom of the page.
     46 5. Click the *Propose changes* button.
     47 
     48 ### From command line
     49 
     50 The instructions describe the main `lvgl` repository but it works the same way for the other repositories.
     51 1. Fork the [lvgl repository](https://github.com/lvgl/lvgl). To do this click the "Fork" button in the top right corner.
     52 It will "copy" the `lvgl` repository to your GitHub account (`https://github.com/<YOUR_NAME>?tab=repositories`)
     53 2. Clone your forked repository.
     54 3. Add your changes. You can create a *feature branch* from *master* for the updates: `git checkout -b the-new-feature`
     55 4. Commit and push your changes to the forked `lvgl` repository.
     56 5. Create a PR on GitHub from the page of your `lvgl` repository (`https://github.com/<YOUR_NAME>/lvgl`) by clicking the *"New pull request"* button. Don't forget to select the branch where you added your changes.
     57 7. Set the base branch. It means where you want to merge your update. In the `lvgl` repo both the fixes and new features go to `master` branch.
     58 8. Describe what is in the update. An example code is welcome if applicable.
     59 9. If you need to make more changes, just update your forked `lvgl` repo with new commits. They will automatically appear in the PR.
     60 
     61 ### Commit message format
     62 The commit messages format is inspired by [Angular Commit Format](https://gist.github.com/brianclements/841ea7bffdb01346392c).
     63 
     64 The following structure should be used:
     65 ```
     66 <type>(<scope>): <subject>
     67 <BLANK LINE>
     68 <body>
     69 <BLANK LINE>
     70 <footer>
     71 ```
     72 
     73 Possible `<type>`s:
     74 - `fix` bugfix in the source code.
     75 - `feat` new feature
     76 - `arch` architectural changes
     77 - `perf` changes that affect the performance
     78 - `example` anything related to examples (even fixes and new examples)
     79 - `docs` anything related to the documentation (even fixes, formatting, and new pages)
     80 - `test` anything related to tests (new and updated tests or CI actions)
     81 - `chore` any minor formatting or style changes that would make the changelog noisy
     82 
     83 `<scope>` is the module, file, or sub-system that is affected by the commit. It's usually one word and can be chosen freely.
     84 For example `img`, `layout`, `txt`, `anim`. The scope can be omitted.
     85 
     86 `<subject>` contains a short description of the change:
     87 - use the imperative, present tense: "change" not "changed" nor "changes"
     88 - don't capitalize the first letter
     89 - no dot (.) at the end
     90 - max 90 characters
     91 
     92 `<body>` optional and can be used to describe the details of this change.
     93 
     94 `<footer>` shall contain
     95 - the words "BREAKING CHANGE" if the changes break the API
     96 - reference to the GitHub issue or Pull Request if applicable.
     97 
     98 Some examples:
     99 ```
    100 fix(img): update size if a new source is set
    101 ```
    102 
    103 ```
    104 fix(bar): fix memory leak
    105 
    106 The animations weren't deleted in the destructor.
    107 
    108 Fixes: #1234
    109 ```
    110 
    111 ```
    112 feat: add span widget
    113 
    114 The span widget allows mixing different font sizes, colors and styles.
    115 It's similar to HTML <span>
    116 ```
    117 
    118 ```
    119 docs(porting): fix typo
    120 ```
    121 
    122 ## Developer Certification of Origin (DCO)
    123 
    124 ### Overview
    125 
    126 To ensure all licensing criteria are met for every repository of the LVGL project, we apply a process called DCO (Developer's Certificate of Origin).
    127 
    128 The text of DCO can be read here: [https://developercertificate.org/](https://developercertificate.org/).
    129 
    130 By contributing to any repositories of the LVGL project you agree that your contribution complies with the DCO.
    131 
    132 If your contribution fulfills the requirements of the DCO no further action is needed. If you are unsure feel free to ask us in a comment.
    133 
    134 ### Accepted licenses and copyright notices
    135 
    136 To make the DCO easier to digest, here are some practical guides about specific cases:
    137 
    138 #### Your own work
    139 
    140 The simplest case is when the contribution is solely your own work.
    141 In this case you can just send a Pull Request without worrying about any licensing issues.
    142 
    143 #### Use code from online source
    144 
    145 If the code you would like to add is based on an article, post or comment on a website (e.g. StackOverflow) the license and/or rules of that site should be followed.
    146 
    147 For example in case of StackOverflow a notice like this can be used:
    148 ```
    149 /* The original version of this code-snippet was published on StackOverflow.
    150  * Post: http://stackoverflow.com/questions/12345
    151  * Author: http://stackoverflow.com/users/12345/username
    152  * The following parts of the snippet were changed:
    153  * - Check this or that
    154  * - Optimize performance here and there
    155  */
    156  ... code snippet here ...
    157 ```
    158 
    159 #### Use MIT licensed code
    160 As LVGL is MIT licensed, other MIT licensed code can be integrated without issues.
    161 The MIT license requires a copyright notice be added to the derived work. Any derivative work based on MIT licensed code must copy the original work's license file or text.
    162 
    163 #### Use GPL licensed code
    164 The GPL license is not compatible with the MIT license. Therefore, LVGL can not accept GPL licensed code.
    165 
    166 ## Ways to contribute
    167 
    168 Even if you're just getting started with LVGL there are plenty of ways to get your feet wet.
    169 Most of these options don't even require knowing a single line of LVGL code.
    170 
    171 Below we have collected some opportunities about the ways you can contribute to LVGL.
    172 
    173 ### Give LVGL a Star
    174 
    175 Show that you like LVGL by giving it star on GitHub!
    176 <!-- Place this tag in your head or just before your close body tag. -->
    177 <script async defer src="https://buttons.github.io/buttons.js"></script>
    178 <!-- Place this tag where you want the button to render. -->
    179 <a class="github-button" href="https://github.com/lvgl/lvgl" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star lvgl/lvgl on GitHub">Star</a>
    180 
    181 This simple click makes LVGL more visible on GitHub and makes it more attractive to other people.
    182 So with this, you already helped a lot!
    183 
    184 ### Tell what you have achieved
    185 
    186 Have you already started using LVGL in a [Simulator](/get-started/platforms/pc-simulator), a development board, or on your custom hardware?
    187 Was it easy or were there some obstacles? Are you happy with the result?
    188 Showing your project to others is a win-win situation because it increases your and LVGL's reputation at the same time.
    189 
    190 You can post about your project on Twitter, Facebook, LinkedIn, create a YouTube video, and so on.
    191 Only one thing: On social media don't forget to add a link to `https://lvgl.io` or `https://github.com/lvgl` and use the hashtag `#lvgl`. Thank you! :)
    192 
    193 You can also open a new topic in the [My projects](https://forum.lvgl.io/c/my-projects/10) category of the Forum.
    194 
    195 The [LVGL Blog](https://blog.lvgl.io) welcomes posts from anyone.
    196 It's a good place to talk about a project you created with LVGL, write a tutorial, or share some nice tricks.
    197 The latest blog posts are shown on the [homepage of LVGL](https://lvgl.io) to make your work more visible.
    198 
    199 The blog is hosted on GitHub. If you add a post GitHub automatically turns it into a website.
    200 See the [README](https://github.com/lvgl/blog) of the blog repo to see how to add your post.
    201 
    202 Any of these help to spread the word and familiarize new developers with LVGL.
    203 
    204 If you don't want to speak about your project publicly, feel free to use [Contact form](https://lvgl.io/#contact) on lvgl.io to private message to us.
    205 
    206 ### Write examples
    207 As you learn LVGL you will probably play with the features of widgets. Why not publish your experiments?
    208 
    209 Each widgets' documentation contains examples. For instance, here are the examples of the [Drop-down list](/widgets/core/dropdown#examples) widget.
    210 The examples are directly loaded from the [lvgl/examples](https://github.com/lvgl/lvgl/tree/master/examples) folder.
    211 
    212 So all you need to do is send a [Pull request](#pull-request) to the [lvgl](https://github.com/lvgl/lvgl) repository and follow some conventions:
    213 - Name the examples like `lv_example_<widget_name>_<index>`.
    214 - Make the example as short and simple as possible.
    215 - Add comments to explain what the example does.
    216 - Use 320x240 resolution.
    217 - Update `index.rst` in the example's folder with your new example. To see how other examples are added, look in the [lvgl/examples/widgets](https://github.com/lvgl/lvgl/tree/master/examples/widgets) folder.
    218 
    219 ### Improve the docs
    220 
    221 As you read the documentation you might see some typos or unclear sentences. All the documentation is located in the [lvgl/docs](https://github.com/lvgl/lvgl/tree/master/docs) folder.
    222 For typos and straightforward fixes, you can simply edit the file on GitHub.
    223 
    224 Note that the documentation is also formatted in [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
    225 
    226 ### Report bugs
    227 As you use LVGL you might find bugs. Before reporting them be sure to check the relevant parts of the documentation.
    228 
    229 If it really seems like a bug feel free to open an [issue on GitHub](https://github.com/lvgl/lvgl/issues).
    230 
    231 When filing the issue be sure to fill out the template. It helps find the root of the problem while avoiding extensive questions and exchanges with other developers.
    232 
    233 ### Send fixes
    234 The beauty of open-source software is you can easily dig in to it to understand how it works. You can also fix or adjust it as you wish.
    235 
    236 If you found and fixed a bug don't hesitate to send a [Pull request](#pull-request) with the fix.
    237 
    238 In your Pull request please also add a line to [`CHANGELOG.md`](https://github.com/lvgl/lvgl/blob/master/CHANGELOG.md).
    239 
    240 ### Join the conversations in the Forum
    241 It feels great to know you are not alone if something is not working. It's even better to help others when they struggle with something.
    242 
    243 While you were learning LVGL you might have had questions and used the Forum to get answers. As a result, you probably have more knowledge about how LVGL works.
    244 
    245 One of the best ways to give back is to use the Forum and answer the questions of newcomers - like you were once.
    246 
    247 Just read the titles and if you are familiar with the topic don't hesitate to share your thoughts and suggestions.
    248 
    249 Participating in the discussions is one of the best ways to become part of the project and get to know like-minded people!
    250 
    251 ### Add features
    252 If you have created a cool widget, or added useful feature to LVGL feel free to open a new PR for it.
    253 We collect the optional features (a.k.a. plugins) in [lvgl/src/extra](https://github.com/lvgl/lvgl/tree/master/src/extra) folder so if you are interested in adding a new features please use this folder.
    254 The [README](https://github.com/lvgl/lvgl/blob/master/src/extra/README.md) file describes the basics rules of contribution and also lists some ideas.
    255 
    256 For further ideas take a look at the [Roadmap](/ROADMAP) page. If you are interested in any of them feel free to share your opinion and/or participate in the implementation.
    257 
    258 Other features which are (still) not on the road map are listed in the [Feature request](https://forum.lvgl.io/c/feature-request/9) category of the Forum.
    259 
    260 When adding a new features the followings also needs to be updated:
    261 - Update [lv_conf_template.h](https://github.com/lvgl/lvgl/blob/master/lv_conf_template.h)
    262 - Add description in the [docs](https://github.com/lvgl/lvgl/tree/master/docs)
    263 - Add [examples](https://github.com/lvgl/lvgl/tree/master/examples)
    264 - Update the [changelog](https://github.com/lvgl/lvgl/tree/master/docs/CHANGELOG.md)
    265 
    266 ### Become a maintainer
    267 
    268 If you want to become part of the core development team, you can become a maintainer of a repository.
    269 
    270 By becoming a maintainer:
    271 - You get write access to that repo:
    272   - Add code directly without sending a pull request
    273   - Accept pull requests
    274   - Close/reopen/edit issues
    275 - Your input has higher impact when we are making decisions
    276 
    277 You can become a maintainer by invitation, however the following conditions need to met
    278 1. Have > 50 replies in the Forum. You can look at your stats [here](https://forum.lvgl.io/u?period=all)
    279 2. Send > 5 non-trivial pull requests to the repo where you would like to be a maintainer
    280 
    281 
    282 If you are interested, just send a message (e.g. from the Forum) to the current maintainers of the repository. They will check if the prerequisites are met.
    283 Note that meeting the prerequisites is not a guarantee of acceptance, i.e. if the conditions are met you won't automatically become a maintainer.
    284 It's up to the current maintainers to make the decision.
    285 
    286 ### Move your project repository under LVGL organization
    287 Besides the core `lvgl` repository there are other repos for ports to development boards, IDEs or other environment.
    288 If you ported LVGL to a new platform we can host it under the LVGL organization among the other repos.
    289 
    290 This way your project will become part of the whole LVGL project and can get more visibility.
    291 If you are interested in this opportunity just open an [issue in lvgl repo](https://github.com/lvgl/lvgl/issues) and tell what you have!
    292 
    293 If we agree that your port fit well into the LVGL organization, we will open a repository for your project where you will have admin rights.
    294 
    295 To make this concept sustainable there a few rules to follow:
    296 - You need to add a README to your repo.
    297 - We expect to maintain the repo to some extent:
    298   - Follow at least the major versions of LVGL
    299   - Respond to the issues (in a reasonable time)
    300 - If there is no activity in a repo for 1 year it will be archived