Pull Requests

Merging new code into the lvgl/lvgl and other repositories happens via Pull Requests (PR for short). A PR is a notification like "Hey, I made some updates to your project.

Edit on GitHub

Merging new code into the lvgl/lvgl and other repositories happens via Pull Requests (PR for short). 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." 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. You can see what it looks like on GitHub for LVGL here: https://github.com/lvgl/lvgl/pulls.

To add your changes you can edit files online on GitHub and send a new Pull request from there (recommended for small changes) or add the updates in your favorite editor/IDE and use git to publish the changes (recommended for more complex updates).

From GitHub

Navigate to the file you want to edit.
Click the Edit button in the top right-hand corner.
Add your changes to the file.
Add a commit message at the bottom of the page.
Click the Propose changes button.

From Your Local Workstation

These instructions describe the main lvgl repository but it works the same way any remote Git repository.

Fork the lvgl repository. To do this click the "Fork" button in the top right corner. It will "copy" the lvgl repository to your GitHub account (https://github.com/<YOUR_NAME>?tab=repositories)
Clone your forked repository.
Add your changes. You can create a feature branch from the master branch for the updates: git checkout -b <new-feature-branch-name>
Commit and push your changes to your forked lvgl repository.
Create a PR on GitHub from the page of your forked 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.
Set the base branch where you want to merge your update. In the lvgl repo both fixes and new features should be directed to the master branch.
Describe what is in the update. Example code is welcome if applicable.
If you need to make more changes, just update your forked lvgl repo with new commits. They will automatically appear in the PR.

Commit Message Format

The commit messages format is inspired by Angular Commit Format.

The following structure should be used:

<type>(<scope>)!: <subject>
            <--- blank line
<body>
            <--- blank line
<footer>

The ! after the scope is optional and is used to flag breaking changes (see Breaking Changes below).

Possible <type>s:

feat new feature
fix bugfix in LVGL source code
arch architectural changes
perf changes that affect performance
example anything related to examples (including fixes and new examples)
refactor code restructuring without changing behavior
revert reverting a previous commit
docs anything related to documentation (including fixes, formatting, and new pages)
style code formatting changes (not CSS-like style)
test anything related to tests (new and updated tests or CI actions)
chore any minor formatting or style changes that would make the changelog noisy
ci changes to CI configuration files and scripts
build changes that affect the build system or external dependencies

<scope> is the name of the module, file, or subsystem affected by the commit. It's usually one word and can be chosen freely. For example img, layout, txt, anim. The scope is required for most types but can be omitted for chore, docs, and ci.

<subject> contains a short description of the change following these guidelines:

use the imperative mood: e.g. present tense "change", not "changed" nor "changes";
don't capitalize the first letter;
no period (.) at the end;
max 90 characters.

<body> optional and can be used to describe the details of this change.

<footer> shall contain:

begin it with "BREAKING CHANGE" if the changes break the API;
reference to the GitHub issue or Pull Request if applicable. (See Linking a pull request to an issue for details.)

Breaking Changes

If your commit introduces a change that breaks backward compatibility (e.g. removes or renames a public API, changes a function signature, or alters existing behavior in a way that requires callers to update their code), it must be flagged the following ways:

1. Add ! after the scope in the subject line to make the breaking change immediately visible in the commit history:

feat(drm)!: replace lv_drm_init() arguments

2. Add a BREAKING CHANGE entry in the footer to describe what changed and how to migrate:

feat(drm)!: replace lv_drm_init() arguments

The card and connector arguments have been merged into a single
device path string for consistency with other driver APIs.

BREAKING CHANGE: lv_drm_init(card, connector) is now
lv_drm_init(device). Replace calls like lv_drm_init(0, 1) with
lv_drm_init("/dev/dri/card0").

Using both ! and BREAKING CHANGE together is recommended for maximum clarity, the ! signals at a glance that the commit is breaking, while the footer explains exactly what callers need to update.

Commit Message Examples

fix(image): update size when a new source is set

fix(bar): fix memory leak

The animations weren't deleted in the destructor.

Fixes: #1234

feat(span): add span widget

The span widget allows mixing different font sizes, colors and styles.
It's similar to HTML <span>

docs(porting): fix typo

chore: bump version to release candidate tag

feat(drm)!: replace lv_drm_init() arguments

BREAKING CHANGE: lv_drm_init(card, connector) is now
lv_drm_init(device). Replace calls like lv_drm_init(0, 1) with
lv_drm_init("/dev/dri/card0").

PR Title

Since the repository uses squash merge by default, the PR title becomes the final commit message. Please make sure your PR title follows the same format described above.

A CI check (Verify PR title format) will automatically verify the format when you open or update a PR. If the check fails, simply edit your PR title to fix the format — the check will re-run automatically.

If your PR contains multiple independent commits that should not be squashed (i.e. the maintainer will use rebase merge), include "don't squash" in the PR title. The title check will be skipped in this case.

Automated Checker

You can validate commit messages locally using the checker script:

bash

# Check a single message
python3 scripts/commit_msg_check.py --check-title "feat(draw): add gradient support"

# Check commits between base branch and HEAD
python3 scripts/commit_msg_check.py --base origin/master

# Run self-tests
python3 scripts/commit_msg_check.py --self-test