Habari on github

From Habari Project

Jump to: navigation, search

The Habari project uses github for source control and issue tracking.

See the announcement for why we moved to github.

Contents

Habari repositories on github

The main advantage of running Habari directly from the source control system is that it makes upgrading simple.

Most Habari users just want the code to run Habari—that's what we package for download—and not the developer-focussed tests, design and scripts. As such, there are multiple Habari repositories on github.

  • habari - This is the equivalent of what was in Subversion's trunk/htdocs, and is what will now be packaged for download. It includes the system repo as a submodule.
  • system - This is the equivalent of what was in Subversion's trunk/htdocs/system, and contains only the system components of the Habari software.

Many people will only use those two. There are four other repositories:

  • tests - This is the equivalent of what was in Subversion's trunk/tests, and can be added to your Habari installation to run unit tests.
  • scripts - This is the equivalent of what was in Subversion's trunk/scripts, and contains various utility scripts, some of which we use on the habariproject.org server.
  • design - This is the equivalent of what was in Subversion's trunk/design, and contains design elements (PSDs, AIs, and specs) that are used for building Habari's user interface.
  • doc - This is the equivalent of what was in Subversion's trunk/htdocs/doc, and contains the Habari documentation / manual.

Installing Habari From Git

Many users use a checkout of the current stable version of Habari to run their web sites, and then update Habari's code directly from the source code repository. This is a process to achieve that:

  1. Clone the Habari repo to your server: git clone https://github.com/habari/habari.git htdocs
  2. Initialize and update the system submodule: cd htdocs; git submodule update --init

This will create a full, current Habari source package within the htdocs directory. You can install it wherever you like.

When there is a full Habari version update, change to the htdocs directory and run: git pull;git submodule update

Note: if checkout fails with a 403 error, ensure that your git version is at least 1.7.x.x

Updating to the in-development version of Habari

The above steps explain how to keep your Habari version in sync with Habari releases. The development version of Habari is usually quite stable, and using it means you get the latest bug fixes and features. To keep up with the latest developments, create a working copy like explained above, and then do this:

  1. Switch the system submodule to the master branch: cd system;git checkout master

This will allow you to pull updates for the system repo independently from the main Habari checkout. When you want to update the system directory with the latest code, simply change to the system directory and run: cd system;git pull

Versioning your sites

Versioning Locally

When you clone the Habari repo to your server, it is its own personal copy of the repo, therefore you can add new files and directories to it, including your configuration files, themes, or plugins.

To add files for directories, simply add them to your local repo and commit them. For example, to store your site configuration, do this: git add config.php;git commit -m "Adding my config file."

Note: You should not do this if you can commit to the core repo, because if you git push this change, it will become part of everyone's checkout. Instead, you could fork the core repo, where there is no danger of this happening.

This is useful for tracking changes that you make to your own site, but the changes are only stored locally.

Versioning Remotely

If you want to version your site on github, you'll need to create a repository there that you can push to. You can do this by forking the habari repo through the github interface, and cloning it instead.

Github-fork.png

Note: Forking or cloning habari/habari will by default add a .gitignore file that ignores config.php, user/habari.db, user/plugins/* and user/themes/*. If you want to track changes to any of these files, edit accordingly.

You can then make changes, commit them, and push them to your fork. For example, to version a theme that you're running on the site, do this: git add user/themes/my-great-theme;git commit -m "Adding my great theme."; git push

Doing this lets you set up your site locally and then clone it on a server.

Note: If you add your config.php to your local repo, make sure you do NOT push this update to an publicly hosted copy/fork of your repo as you WILL reveal security information you really don't want to. If you want to version your config remotely, you'll have to pay for a private repo or host it somewhere other than github.

Remember that you've only forked the habari repo at this stage, not the system repo, so that still points to the official repository. You can't push any changes to system, so if you want to contribute to Habari's development, you'll need to follow the instructions below.

Versioning Multiple Sites Remotely

Many people run multiple sites using Habari, and of course it's useful to keep them versioned, but you can't have multiple forks of the habari repo that are all called habari. To version multiple sites on github, simply rename your forks as you create them.

First, access the admin of your fork.

Github-admin.png

Next, change the name to something useful, such as the title of the site being versioned.

Github-rename-repo.png

Once you've renamed your repo, you can fork again.

Moving a Subversion Installation to Git

If you have an existing checkout from subversion, you probably want to move that to use git instead.

  1. Rename the directory that holds your Habari installation.
  2. Create a replacement directory to hold your new Habari installation.
  3. Install from github, as described in the sections above, according to your needs.
  4. Delete the .svn directories from the user directory of your original installation.
  5. Copy your config.php, .htaccess and the contents of your user directory from your original installation to your new installation.

If you need to minimise the disruption to a site while you move it from subversion to git, you might want to redirect traffic that would normally go to Habari to a maintenance page instead. For example, for Apache, you could use something like this in an .htaccess file to redirect all traffic to your Habari installation to a maintenance page, after you've created your replacement directory.

RewriteEngine On
RewriteBase /path/to/habari
RewriteRule . maintenance.html

Installing to Contribute to Habari

Following the instructions above are enough if you want to use Habari and keep your own sites in version control. However, if you want to contribute to Habari (and we'd love you to!) then you'll need to set things up slightly differently. Here we describe how to do that.

Note that you'll need to have a working git install, Github account, and your SSH keys associated with your Github account. They have great instructions on doing this available for multiple OSes.

  1. Fork the habari/habari repo through the github web interface.
  2. Fork the habari/system repo through the github web interface.
  3. Clone your fork of the habari repo to your server: git clone git@github.com:{your-git-user}/habari.git htdocs
  4. Edit .gitmodules in your clone to change the URL of the system submodule to point to your clone of system instead of the habari clone of system.
  5. Commit the change of .gitmodules to your local repo and push it to your fork on github: git add .gitmodules;git commit -m "Point to my system fork."
  6. Update your working copy of your fork of the system submodule: git submodule update --init
  7. Switch the system submodule to the master branch: cd system;git checkout master

This puts you in a position to make edits to Habari core.

To make edits to your fork of the Habari core:

  1. Make your changes within system.
  2. While the current directory is system or a subdirectory of system, add and commit your changes to your local repo. For example, to commit all changes: git commit -a -m "Change the floogle, making Habari more awesome."
  3. Push changes from your local repo to your fork on github: git push
  4. Change to the root of your local habari repo (above the system directory) and change the submodule to point to your new commit: git add system;git commit -m "Updated the pointer to system"
  5. Push your change in the local habari repo to your fork on github: git push

To request that your changes be applied to Habari core, visit your fork on github, select the commit for which you would like to make a request, and click on the "Pull Request" button. Describe the change, and submit your request.

Contributing as a core dev

Things are a little different if you're a core developer because you can push code directly to the Habari repos instead of creating pull requests. The steps below describe how to set up an installation of Habari so that you can commit directly.

Note that you'll need to have a working git install, Github account, and your SSH keys associated with your Github account. They have great instructions on doing this available for multiple OSes.

  1. Clone the Habari repo to your server: git clone git@github.com:habari/habari.git htdocs
  2. Initialize and update the system submodule: cd htdocs; git submodule update --init
  3. Switch the system submodule to the master branch: cd system;git checkout master
  4. Make your changes within system.
  5. While the current directory is system or a subdirectory of system, add and commit your changes to your local repo. For example, to commit all changes: git commit -a -m "Change the floogle, making Habari more awesome.". You can reference a GitHub Issue using habari/habari#123 within the commit message where '123' is the ticket number. Unfortunately, GitHub's auto issue closure (using the "Closes #123" string) doesn't seem to work using this reference so you will need to manually close the ticket.
  6. Push changes from your local repo to Habari on github: git push

You could also develop on your own fork, as described above. Alternatively, you could develop on a different branch rather than master, either an existing one using git checkout some-feature-branch or a new one using git checkout -b my-new-feature.

Running Habari as a core dev

As a core developer, you're probably running Habari for yourself as well. You can version your sites in the same way as described above but there's one important distinction: you do have access to push to the system repo, so at the least you should be careful what changes you make.

To be on the safe side and make it harder to commit unwanted changes, you might want to rename the named remote of the system repo. When you do a clone, git records the location you cloned from into its config with an alias of "origin". By default, if you run git pull or git push that's the repo that git uses. You can rename the origin remote with the following command: git remote rename origin core

Personal tools