Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
155 lines (107 sloc) 5 KB

Improving and maintaining a TurnKey app

Lets say you want to fix a bug, add functionality, upgrade the version of upstream software, or make any other change. This guide should help you do that and get your changes included in the official TurnKey app.

For example, say a new version of projectpier has been released, and we want to update TurnKey ProjectPier.

Fork and clone the source

As described in the TurnKey Git Flow, GitHub is used to facilitate collaboration, so the first thing to do is fork the source code:

That's it. You've successfully forked the projectpier repository, but so far it only exists on GitHub.

To be able to work on the project you'll need to clone it:

cd /turnkey/fab/products

So far so good. When a repository is cloned, it has a default remote called origin that points to your fork on GitHub, not the original repository it was forked from.

To keep track of the original repository, you need to add another remote, we'll call it upstream:

cd projectpier
git remote add upstream

# Fetch any new changes to the original repository
git-fetch upstream

# Merge any changes fetched into your working branch
git merge upstream/master

Make your changes

OK, so now we're almost ready to make our changes. As described above, we are updating the version of projectpier.

Create a branch

The first thing to do is create a branch for the update. Note that you have only one pull request per branch:

git-checkout -b upgrade-to-vXX.YY

Perform change

So now we are ready to make our changes. It's recommended to read the release notes of new versions to see if there are any other changes that might need to be made. For arguments sake, lets say there aren't.

We get the new versions download URL as well as the md5sum, and update conf.d/downloads.


And we're done, not so hard. Lets perform a build for testing, but instead of building the ISO, we'll take a quick shortcut and specify CHROOT_ONLY=y. This excludes boot-related packages and stops the build at the root.sandbox stage:


If there were any issues during the build, we'll need to fix them, and run make CHROOT_ONLY=y again. Note that the build will pick up from where it left off, and re-make the target that caused the issue.

Once the CHROOT_ONLY build is successful, lets test it:

fab-chroot build/root.sandbox
/etc/init.d/mysql start
/etc/init.d/apache2 start

# on host system, browse to http://ip-of-tkldev-vm
# verify there are no issues

/etc/init.d/apache2 stop
/etc/init.d/mysql stop

Note: If testing via the Hub you will need to adjust the Firewall rules to open any relevant ports (e.g. 80 for http, etc).

Testing complete? Let's perform a cleanup:

deck -D build/root.sandbox
make clean

Cautionary note: not all changes can be tested reliably (or at all) inside chroot using the CHROOT_ONLY shortcut. For large changes or changes that may effect the boot process (e.g., inithooks) it is recommended not to use CHROOT_ONLY. Instead, perform a full build and test the ISO in a VM.


Now we commit our example change to the repository:

$ git-status
# On branch upgrade-to-vXX.YY
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#   modified:   conf.d/downloads
no changes added to commit (use "git add" and/or "git commit -a")

$ git-add conf.d/downloads
$ git-commit -m "Upgraded projectpier to version XX.YY"

Push changes to GitHub and submit a Pull Request

Now that you're finished hacking and all changes are committed, you need to push them to your GitHub repository:

git-push origin upgrade-to-vXX.YY

Last thing to do is send a pull request so the maintainer or one of the core developers can review, sign off, and perform the merge in the official repository.

Hooray! You did it.

If for some reason the maintainer or one of the core developers has a problem with your change, they won't want to merge until fixed.

The good news is that whenever you commit and push more changes to that branch of your code, they will be included in that original pull request until it is closed.

You can’t perform that action at this time.