Modifying an Existing ClearOS 7 App
If don't have your development environment or ClearOS source code ready, please jump to the Getting Started document to read about how to get that done. If you already have everything ready to go, let's dive into modifying existing apps.
This guide covers apps in ClearOS 7. For ClearOS 6, you can use this older guide for contributing to ClearOS 6 apps in Github.
This guide assumes that you are already pretty handy at coding on ClearOS and want to modify or suggest modifications to existing apps in ClearOS. Generally speaking, you will need to work with the team of developers who maintain the app to get your changes approved. For now, please contact ClearCenter or ClearFoundation members for help getting this done. You may even be asked to work with the team in a group technical discussion which is generally done on Tuesdays and Thursdays around 18:30 UTC.
If you want to get more familiar with the programming environment under ClearOS, try your hand at the 'Hello World' app, or create a new one first. Another way to get familiar is to work on existing projects. If that is what you are wanting to do, you've come to the right place.
Prepping the Editable App
On your development environment, you may need to install the app already so that you can be sure to have all the libraries of other apps which might be required so that you can get a proper view of the app while you develop. For this example, install the Samba Directory app:
yum install app-samba-directory
You will need to have access to the repository where the app is stored. For most open source applications, these apps are stored in Github. Other apps may be in other repositories. Contact ClearCenter if you do not see the app that you want to work on for more details on how to access the source code.
Grab a copy of the code. To do this, create your own Github account and then you will copy the source code for the app to your own repo. This is called 'forking' since the code you will modify will differ from the code on this site for as long as you are working on it. When your changes are accepted and the code is working for you, the team can take your changes and apply them back into the mainline code. This is called merging. For this example, we'll be forking the Samba Directory app in this example.
Now that YOU have a copy, you will clone that copy to your development environment. SSH to your environment as your dev user (not root), change into the apps directory and then grab the source that you want and pull down the clone from your own repo (change the username to the one you used to register with your github account):
mkdir -p ~/apps
git clone firstname.lastname@example.org:/app-samba-directory.git samba-directory
Alternately, if you want to clone the repo anonymously you can clone directly from the repo:
mkdir -p ~/apps
git clone https://github.com/clearos/app-samba-directory.git samba-directory
If you use this method, you will already need to have rights to upload changes to the central repo. If you don't have this method, use the forked method above.
Update ClearOS Development Configuration
In the ~/.clearos file, the following configuration needs to be added:
\clearos\framework\Config::$apps_paths = 'apps';
If you have already been developing apps, like with the 'Hello World!' app then this is already done.
Once the app is in place, reload the webconfig interface from your developer's home directory:
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!
Pushing Changes and Triggering Events
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:
verified-updates (ClearOS Business and ClearOS Home subscriptions only)