defconfigto enable a driver
masterdevelopment branch where the next release takes shape, and stable release branches, e.g.
libreelec-9.0that accumulate release-specific changes (commits) over time.
git cloneour sources and start building, but if you want to maintain personal customisations and changes over time it's better to
forkour sources to your own git repo. Having your own fork makes the process of storing, sustaining, and sharing your changes easier. Forking is done online by visiting the LibreELEC repo and then pressing the fork button (top right of the screen). GitHub will make a copy of our sources under your own user account. Now instead of cloning OUR sources you
git clonea copy of YOUR sources to your local hard-drive.
masterbranch and release branches like
libreelec-9.2which contain a sequence of commits. When you clone your repo to your local drive, git automatically creates references to your copy on GitHub which is the
originof your local sources. To update your local branches with changes from our
upstreambranches, we will define a
remoterepo. You can add many remote(s), but we will add just one:
checkouta new branch from the one you want to modify. For example, to modify the
libreelec-9.2branch, we switch to it, then create the "mychanges" topic branch:
commitchanges to the working (topic) branch. The mantra for committing is "commit early, commit often" because it's always simple to combine (squash) commits together at a later stage, but hard to split a large commit into many smaller pieces. Commits can document changes to a single file or a collection of files, with a readable "commit message" that describes the changes. LibreELEC has a "house style" for commit messages:
tag: summary of changes madewhere
tagis the name of the package being changed or a functional area of the build system and
summary of changes madeexplains in brieft what the change does. It helps to make them descriptive so you can read the
git loglater and understand which commit changed something. For example, if we enable an extra driver or module in the Linux kernel:
upstreambranches and your local fork falls behind. To update your "mychanges" topic branch you must first commit any unsaved changes, then switch back to the branch it was based upon, e.g. the
fetchthe latest changes from the
upstreambranch to our local cache, then reset the local copy of the branch to match the upstream one:
libreelec-9.2branch contains the latest changes we can change back to our
mychangestopic branch and
rebasethe branch. Rebasing re-applies the single or handful of changes that you made (and committed) to the branch you are rebasing against, e.g.
mychangesbranch matches the upstream
libreelec-9.2branch, with your local changes applied on top.
file Bcommits like this:
fixupwhich combine commits. In the sequence below, the first commit is at the top, and we want to combine the next two minor changes into it. If you
squashcommits you will be asked to edit the commit messages (choose which of the commits should be used for the message) while
fixupcombines the lower (second) commit into the upper (first) commit and uses the first commit message without prompting. For example:
pushingyour local changes back to your
originbranch on GitHub. If something gets messed up in your local branch (and when you are starting out with git, stuff will get messed up!) you can always reset your local branch to the previous known-good state stored on GitHub. Pushing the changes is simple:
mychangesbranch the branch history will have different references and a force-push will be needed:
upstreamin our repo so you don't need to maintain them in your
downstreamfork, you'll need to submit a
pull request(referred to as a PR.) This is done in the GitHub interface. You need to push your changes to your origin branch, and then when you view the code on GitHub, select the "pull request" button. You'll be prompted to select the repo/branch to send the request to, e.g.
LibreELEC.tv/masterand you'll give the request a name and description. If your pull request modifies code, please include a good description of the problem that your changes solve or what the feature is that you added, and (important!) the testing you conducted. So called "blind requests" where there is no evidence of testing and no meaningful explanation of the change, are rarely merged (or merged quickly) into our codebase.
masterbranch first, even if the target for your changes is the current stable release branch. This way the branches remain in sync, and we don't have orphaned features.