OSMC wouldn’t be where it is without the excellent volunteers behind it. We strongly encourage anyone who is interested in improving OSMC to do so. In this article, we will explore how to contribute code changes back to OSMC so that your changes are incorporated in future releases.
We covered getting the code and setting up a basic development environment in 'Getting involved with OSMC Development’. Once you have this environment set up, you may wish to look at other articles on how to build parts of OSMC.
After you’ve got a copy of the OSMC code in your own repository, you’ll likely want to make changes and get them submitted for inclusion in OSMC. There are a few conventions that OSMC recommends adhering to so that progress is easier to follow for all developers.
OSMC usually uses a single branch approach, unless there are large, long term changes pending for inclusion. We recommend that you create a new branch off the top of master, before you make your change. This will make it easier for you to keep your changes consistent in the future. It will also permit you to work on more than one feature change a time if submissions are pending inclusion in OSMC.
Your branch should only include commits that make small changes to OSMC to achieve your change. If you are changing more than one part of OSMC, and these changes are not atomic, then you should create two separate branches, and in turn, two separate pull requests.
Commits should also be atomic, and contain as small a change as possible to achieve the desired outcome. You should give your commit a meaningful description, outlining what has changed and for what purpose. You should also use an appropriate prefix for your commit. Some examples are:
[package] [mediacenter-osmc] [installer] [target] [filesystem] Raspberry Pi 2:
You can find more examples simply by looking through the Git commit history.
We do not recommend bumping versions in your commits. This can be done by the maintainer and by avoiding this yourself it will be easier for your changes to be merged and reduce the change for conflicts if the version is bumped above your newer version in the main repository.
Once you submit your pull request, you should receive some comments and advice within a few days. Developers will help you make changes if necessary and will then merge your changes. They will then make it in to the next monthly version of OSMC (link to monthly update).
It’s likely you will be asked to make changes to your pull request, especially if it’s the first time you’ve made a contribution to the OSMC project.
Any further commits you push to your branch will be automatically appended to the pull request. However we would like to avoid unnecessary, additional commits which amend previous changes. You should
We would like to avoid unnecessary ‘fixup’ commits which amend previous changes. You can meld commits in to the previous commit by running the following commands:
git rebase -i HEAD~COMMITNUMBER
In the above example, you should substitute COMMITNUMBER for the number of commits that you have committed to this branch.
You will then see something like this:
pick 441bfe3 [package] [kernel-osmc] Add some patch for blah blah blah pick 82aaba7 [package] [kernel-osmc] Fix blah blah blah patch
In the example above, we have added a patch to the kernel. We have then had to fix this patch, possibly due to a rebase issue. It would not be necessary to include both commits when we submit a pull request, and instead, we could merge the changes in to the original commit.
To do this, you would change
pick for any commits you wish to meld to
fixup as follows:
pick 441bfe3 [package] [kernel-osmc] Add some patch for blah blah blah fixup 82aaba7 [package] [kernel-osmc] Fix blah blah blah patch
This will now adjust your branch to only include one commit. This one commit will contain your improvements of the commit which fixes the package.
You can now push your changes to your repository. This will update the pull request. You will need to force push your changes, as you have changed an already pushed commit. This can be done by appending
--force to your
git push command.
It is recommended you discuss significant changes with developers before you start implementing them. Discussing changes will allow the exploration of feasibility, whether the changes are wanted by the wider community, and the best possible way to make these changes. Our community forum is a great way to discuss the development of the OSMC project.