1.. _contributing: 2 3Contributing 4============ 5 6Introduction 7------------ 8 9Join LVGL's community and leave your footprint in the library! 10 11There are a lot of ways to contribute to LVGL even if you are new to the 12library or even new to programming. 13 14It might be scary to make the first step but you have nothing to be 15afraid of. A friendly and helpful community is waiting for you. Get to 16know like-minded people and make something great together. 17 18So let's find which contribution option fits you the best and help you 19join the development of LVGL! 20 21Ways to contribute 22------------------- 23 24- **Spread the Word**: Share your LVGL experience with friends or on social media to boost its visibility. 25- **Star LVGL** Give us a star on `GitHub <https://github.com/lvgl/lvgl>`__ ! It helps a lot to LVGL more appealing for newcomers. 26- **Report a bug**: Open a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__ if something is not working. 27- **Join our** `Forum <https://forum.lvgl.io/>`__ : Meet fellow developers and discuss questions 28- **Tell your ideas**: If you miss something from LVGL we would love to hear about it in a `GitHub Issue <https://github.com/lvgl/lvgl/issues>`__ 29- **Develop features**: Help to design or develop a feature. See below. 30 31 32Mid and large scale issues are discussed in `Feature planning <https://github.com/lvgl/lvgl/issues/new?assignees=&labels=&projects=&template=feat-planning.yml>`__ issues. 33 34An issue can be developed when all the questions in the issue template are answered and there is no objection from any core member. 35 36We are using GitHub labels to show the state and attributes of the issues and Pull requests. 37If you are looking for contribution opportunities you can `Filter for these labels <https://github.com/lvgl/lvgl/labels>`__ : 38 39- ``Simple``: Good choice to get started with LVGL contribution 40- ``PR needed``: We investigated the issue but it still needs to be implemented 41- ``Review needed``: A Pull request is opened and it needs review/testing 42 43 44.. _contributing_pull_request: 45 46Pull request 47------------ 48 49Merging new code into the lvgl, documentation, blog, examples, and other 50repositories happen via *Pull requests* (PR for short). A PR is a 51notification like "Hey, I made some updates to your project. Here are 52the changes, you can add them if you want." To do this you need a copy 53(called fork) of the original project under your account, make some 54changes there, and notify the original repository about your updates. 55You can see what it looks like on GitHub for LVGL here: 56https://github.com/lvgl/lvgl/pulls. 57 58To add your changes you can edit files online on GitHub and send a new 59Pull request from there (recommended for small changes) or add the 60updates in your favorite editor/IDE and use git to publish the changes 61(recommended for more complex updates). 62 63From GitHub 64~~~~~~~~~~~ 65 661. Navigate to the file you want to edit. 672. Click the Edit button in the top right-hand corner. 683. Add your changes to the file. 694. Add a commit message on the bottom of the page. 705. Click the *Propose changes* button. 71 72From command line 73~~~~~~~~~~~~~~~~~ 74 75The instructions describe the main ``lvgl`` repository but it works the 76same way for the other repositories. 77 781. Fork the `lvgl repository <https://github.com/lvgl/lvgl>`__. To do this click the 79 "Fork" button in the top right corner. It will "copy" the ``lvgl`` 80 repository to your GitHub account (``https://github.com/<YOUR_NAME>?tab=repositories``) 812. Clone your forked repository. 823. Add your changes. You can create a *feature branch* from *master* for the updates: ``git checkout -b <the-new-feature-branch-name>`` 834. Commit and push your changes to the forked ``lvgl`` repository. 845. Create a PR on GitHub from the page of your ``lvgl`` repository (``https://github.com/<YOUR_NAME>/lvgl``) by 85 clicking the *"New pull request"* button. Don't forget to select the branch where you added your changes. 866. Set the base branch. It means where you want to merge your update. In the ``lvgl`` repo both the fixes 87 and new features go to ``master`` branch. 887. Describe what is in the update. An example code is welcome if applicable. 898. If you need to make more changes, just update your forked ``lvgl`` repo with new commits. 90 They will automatically appear in the PR. 91 92.. _contributing_commit_message_format: 93 94Commit message format 95~~~~~~~~~~~~~~~~~~~~~ 96 97The commit messages format is inspired by `Angular Commit 98Format <https://gist.github.com/brianclements/841ea7bffdb01346392c>`__. 99 100The following structure should be used: 101 102.. code-block:: 103 104 <type>(<scope>): <subject> 105 <BLANK LINE> 106 <body> 107 <BLANK LINE> 108 <footer> 109 110Possible ``<type>``\ s: 111 112- ``fix`` bugfix in the source code. 113- ``feat`` new feature 114- ``arch`` architectural changes 115- ``perf`` changes that affect the performance 116- ``example`` anything related to examples (even fixes and new examples) 117- ``docs`` anything related to the documentation (even fixes, formatting, and new pages) 118- ``test`` anything related to tests (new and updated tests or CI actions) 119- ``chore`` any minor formatting or style changes that would make the changelog noisy 120 121``<scope>`` is the module, file, or sub-system that is affected by the 122commit. It's usually one word and can be chosen freely. For example 123``img``, ``layout``, ``txt``, ``anim``. The scope can be omitted. 124 125``<subject>`` contains a short description of the change: 126 127- use the imperative, present tense: "change" not "changed" nor "changes" 128- don't capitalize the first letter 129- no dot (``.``) at the end 130- max 90 characters 131 132``<body>`` optional and can be used to describe the details of this 133change. 134 135``<footer>`` shall contain 136 137- the words "BREAKING CHANGE" if the changes break the API 138- reference to the GitHub issue or Pull Request if applicable. 139 140Some examples: 141 142- fix(img): update size if a new source is set 143- fix(bar): fix memory leak 144 The animations weren't deleted in the destructor. 145 146 Fixes: #1234 147- feat: add span widget 148 149 The span widget allows mixing different font sizes, colors and styles. 150 It's similar to HTML <span> 151- docs(porting): fix typo 152 153.. _contributing_dco: 154 155Developer Certification of Origin (DCO) 156--------------------------------------- 157 158Overview 159~~~~~~~~ 160 161To ensure all licensing criteria are met for every repository of the 162LVGL project, we apply a process called DCO (Developer's Certificate of 163Origin). 164 165The text of DCO can be read here: https://developercertificate.org/. 166 167By contributing to any repositories of the LVGL project you agree that 168your contribution complies with the DCO. 169 170If your contribution fulfills the requirements of the DCO no further 171action is needed. If you are unsure feel free to ask us in a comment. 172 173Accepted licenses and copyright notices 174~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 175 176To make the DCO easier to digest, here are some practical guides about 177specific cases: 178 179Your own work 180^^^^^^^^^^^^^ 181 182The simplest case is when the contribution is solely your own work. In 183this case you can just send a Pull Request without worrying about any 184licensing issues. 185 186Use code from online source 187^^^^^^^^^^^^^^^^^^^^^^^^^^^ 188 189If the code you would like to add is based on an article, post or 190comment on a website (e.g. StackOverflow) the license and/or rules of 191that site should be followed. 192 193For example in case of StackOverflow a notice like this can be used: 194 195.. code-block:: 196 197 /* The original version of this code-snippet was published on StackOverflow. 198 * Post: http://stackoverflow.com/questions/12345 199 * Author: http://stackoverflow.com/users/12345/username 200 * The following parts of the snippet were changed: 201 * - Check this or that 202 * - Optimize performance here and there 203 */ 204 ... code snippet here ... 205 206Use MIT licensed code 207^^^^^^^^^^^^^^^^^^^^^ 208 209As LVGL is MIT licensed, other MIT licensed code can be integrated 210without issues. The MIT license requires a copyright notice be added to 211the derived work. Any derivative work based on MIT licensed code must 212copy the original work's license file or text. 213 214Use GPL licensed code 215^^^^^^^^^^^^^^^^^^^^^ 216 217The GPL license is not compatible with the MIT license. Therefore, LVGL 218cannot accept GPL licensed code. 219
