This document describes how to contribute to existing ClearOS apps on GitHub. If you are developing a new app, read this document instead.
We are going to walk through an example on how manage the UPnP app maintained as a hobby by one of the ClearOS developers. If you plan on contributing a bug fix or feature, please read through the fork and pull documents on github.com:
There are a couple of little gotchas with respect to the repository name and app name. Read on for details.
If you are a new developer to the ClearOS project, you will first need to fork a repository (fork an app) that you wish to work on. Forking a repo allows you to hack away at the code in a branch that cannot affect core development.
<note tip>After completing 2 or 3 contributions to the core code-base, if your patches/features have been accepted, please contact email@example.com and request to be added as a core developer. Once done, you will no longer require having to fork and wait for your patches to be accepted.</note>
Find the app/repository you want to fork. In a browser, head over to GitHub and “Find a Repository” for the app in question. For example, if you wanted to work on the software RAID app manager, search for “raid”. The URL for the project returned will be:
You'll need to be logged into your GitHub account to fork a repository. If you don't have a Git account, you can create one here.
When you are on GitHub *and* logged in *and* viewing the correct repository, click on the “Fork” link.
Select your personal GitHub account to fork to.
Congratulations! You have know forked your first ClearOS repository. An exact copy is now available for cloning (to your ClearOS development environment) using the new URL:
Where <GIT_USERNAME> is your GitHub account username.
Time to clone your forked repo.
ClearOS apps are stored in the repository by their package name, but you want to clone the forked app to its basename. For example, app-raid.git should be cloned to the raid folder:
mkdir -p ~/clearos_core/apps cd ~/clearos_core/apps git clone firstname.lastname@example.org:<GIT_USERNAME>/app-raid.git raid
Where <GIT_USERNAME> is your GitHub account username from the previous step.
In the above example, the ~/clearos_core/apps directory is used for storing any apps…it could be core ClearOS apps or third party apps from developers. Pick whatever directory you want of course, but the ClearOS development environment needs to know where to find it. In the ~/.clearos file, the following configuration needs to be added:
<?php \clearos\framework\Config::$apps_paths = 'clearos_core/apps';
After making the configuration change, reload the development environment:
At this point, you should see the RAID app appear in your webconfig development environment @ https://w.x.y.x:1501 Please keep in mind that any underlying package dependencies hasve not yet been installed. You can install the live version by running:
sudo yum install app-raid
Go ahead and hack away at your code. Don't forget to generate a Pull Request if desired. A pull request lets us know that your forked copy has some changes that we should check out. If we like what we see, we can merge your code into ClearOS and voila! you are a contributor to ClearOS!
Once you are done with your changes, you need to push your commit to your forked repository. In doing so, an automatic event notification system in GitHub will alert the owner(s) of the original repository you forked of your change. It will then be up to the original developers to act on (or ignore) your “pull request”…essentially a merge of the HEAD and forked versions.
If the developers accept the changes, they will then build a revised package and it will go on to eventually end up in the software repositories used by the yum package manager, going through the following quality control levels: