How to start extension development in Git

What is Git?

Git is a "version control system" From http://git-scm.com: "Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. It outclasses SCM tools like Subversion, CVS, Perforce, and ClearCase with features like cheap local branching, convenient staging areas, and multiple workflows. "

You can familiarize yourself with git through a number of useful documentation sites:

• Git Manual: http://git-scm.com/doc
• Git magic: http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html

And of course the Foswiki.org documentation:

• GettingStarted
• GitRepository
• GitCookbook

One key difference between git and subversion. git is local. You have your own local repository. "commit" (recording changes into the repository), "checkout" (extracting files from the respository), are all local. You can then make your local changes available for others to use by "push"ing the change to a remote repository, And download changes from others by "pull"ing them into your local repository.

Step-by-step

1. Registration

First of all you have to be registered on both Github and foswiki.org We'll need your user name that you registered with on Github, and your WikiName in use here on Foswiki.org. When you register, please keep the following in mind.

• If possible use the same email address on your github and foswiki.org registrations.
• And choose your Github "name" so that it can be "wikified" into your Foswiki registration. ie. Joe User on github is JoeUser on foswiki.org

By doing this it makes it easier to associate code changes on github with tasks on foswiki.org.

2. push access on github.

In addition to that, you'll probably want to push changes from your local repository to the foswiki account on github. Normally you can only checkout files from there. To do so, read GettingStarted and after that RequestAccessToGit. Your application will be reviewed and it may take some days until you get access granted, but it's very rare that is is refused.

You don't really have to have write access to the github foswiki account. You can clone a foswiki repository into your local github account, make changes on your own repository, and then issues a "Pull Request" to ask a foswiki developer to apply your change.

3. Installation based on git

Now to the harder part:
There is a detailed tutorial for an installation based on git at GitBasedInstall. This type of installation is not required for extension development, but recommended as it simplifies the installation of extensions and their testing. The main idea of this setup is to "simulate" the installation of extensions instead of really installing them. The files continue to exist in your local git repository, and foswiki uses them as if they were installed. As you surely will be doing modifications to your new extension, uninstall might be difficult on a conventional installation, but very easy on a installation based on git. Use ./pseudo-install.pl all for virtually installing all extensions and ./pseudo-install.pl -uninstall all for uninstalling them again.

To give you an example, let's assume the following:

• Your operating system is a unix-based one.
• You are going to set up a git based installation at /var/www/foswiki.
• You are going to install the standard extensions that are normally shipped with the standard distribution.
• User and group of your webserver configuration are www-data (for both).

So, the following steps would be necessary for the setup:

# Change to the directory where you are going to install:
cd /var/www/foswiki
# Check out the "distro" from git:
git clone https://github.com/foswiki/distro.git .
# Install the standard extensions
cd core
./pseudo-install.pl developer
chown -R www-data:www-data .

To install only one specific extension, enter ./pseudo-install.pl NameOfSpecificExtension.
To uninstall one specific extension, enter ./pseudo-install.pl -uninstall NameOfSpecificExtension.
To uninstall all extensions, enter ./pseudo-install.pl -uninstall all.

If you pseudo-install an extension that you have not cloned from github, pseudo-install will detect this and automatically clone the repository.

By default, the above steps have you running on our "bleeding edge" "master" branch (known as "trunk" in subversion. (see GitBasedInstall). It might happen that the guys working on the core broke something and the installation of the latest revision does not work. In this case, you can easily flip to the Release 1.1.9+ release.

git checkout Release01x01
./pseudo-install developer

4. Create the initial directory for your new extension!

Before we get into further details, maybe you already figured out how your git installation works. If not, here is how it goes:

All development work is done in the master branch,

BuildContrib helps a lot with extensions development, from the initial directory tree and files creation until the upload to Foswiki:Extensions. So, let's create the initial directory tree:

cd /var/www/foswiki
perl core/create_new_extension.pl FooPlugin

The core/create_new_extension.pl takes the name of an extension (it must end in Plugin, Skin or Contrib) and creates the correct initial directory structure. By running it in the top of your foswiki distro clone, it creates the directories in the right location for later "pseudo-install".

5. Submit your new directory to github

Before you can push to github, you need to create an empty repository. You have two choices:

• You can request a Foswiki admin to create the repository in the foswiki project.
• Or you can create an empty repository in your own personal account.

Repositories in the foswiki project require setup with irc, email and web push "hooks". These keep Tasks synchronized with git commits, and publicize your work to IRC and developer email lists. Once a new repository is created on Github, wait an hour before making your first commit. A cron script on foswiki.org runs hourly and automatically creates the required hooks.

(If you have admin rights on https://github.com/foswiki, create the empty repository by clicking the big green "New repository" button. Name it the same as your extension. "FooPlugin". Otherwise an admin will perform this step for you)

Locally:

1. Change to the /var/www/foswiki/FooPlugin directory
2. Set up the git repository on your local machine (ItemXXXX refers to a task identifier. You should always have a task identifier before checking anything in, see Tasks for details)

git init
git add .
git commit -a -m "ItemXXXX: Initial checkin of FooPlugin"

1. In the github repository, copy the URL for your new repository. (Bottom of right sidebar)
2. Set the upstream url

git remote add origin https://github.com/foswiki/FooPlugin.git
git remote -v
git push origin master

You are now directly contributing to development! Be aware that this brings along some additional responsibilities, so please review DeveloperResponsibilities carefully.

6. Start developing your extension!

The basic commands are:

• perl build.pl release to prepare all files necessary for the release of FooPlugin, including the installer script.
• perl build.pl test to run unit tests on your extension.
• perl build.pl upload to upload your extension to the foswiki website.

For detailed information, have a look at BuildContrib and BuildContribCookbook.

Once you generated some files for your new extension (and they are listed in the MANIFEST file), you can include them into your Git based installation. Just:

# Change to the core directory of your installation:
cd /var/www/foswiki/core
# Install your new extension:
./pseudo-install.pl FooPlugin
# Make sure the ownership of all files is still set correctly and according
# to the configuration of user and group of your webserver :
cd ..
chown -R www-data:www-data .

For a trunk installation it might be required to configure apache, so it will support symlinks in core/pub/System:

<Directory "/path/to/trunk_directory/core/pub/System">
    Options FollowSymLinks
</Directory>

Using standard cgi will allow to run the trunk setup on the same machine like some other Foswiki installation, even if e.g. the other installation may use an accelerator like ModPerlEngineContrib. Using trunk and another installation with an accelerator at the same time causes issues. Maybe special setups are possible but it doesn't work as described in a "standard" apache setup with ModPerlEngineContrib).

7. Keep on working!

You want to submit the files you developed on your local computer to git so that other people can help you fixing bugs or improving it? Ok, commit them!

cd /var/www/foswiki/FooPlugin
git commit -m "Item2233: Checking in beta release of FooPlugin"
git push

You want to see what has changed since your last update? Check it!

cd /var/www/foswiki/FooPlugin
git status

You want to update your local copy with the changes someone else did on some files?

cd /var/www/foswiki/FooPlugin
git pull

8. Release your extension

To release it read on in BuildContrib.