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:
And of course the Foswiki.org documentation:
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.
First of all you have to be registered on both Github
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
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:
So, the following steps would be necessary for the setup:
# Change to the directory where you are going to install:
# Check out the "distro" from git:
git clone https://github.com/foswiki/distro.git
# Install the standard extensions
chown -R www-data:www-data .
To install only one specific extension, enter
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
Important: The build tools and unit tests will need a usable Foswiki configuration to operate correctly.
You can configure Foswiki by any of:
- Visit the installation WebHome directory and perform a normal Bootstrap and save the configuration.
- Use the
tools/configure -save command line configuration to prompt and save a usable configuration.
pseudo-install.pl -A to write generate a basic configuration that won't be web usable, but ensures a common stable configuration for repeatable unit tests.
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,
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:
perl core/create_new_extension.pl FooPlugin
takes the name of an extension (it must end in
) 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)
- Change to the
- 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 add .
git commit -a -m "ItemXXXX: Initial checkin of FooPlugin"
- In the github repository, copy the URL for your new repository. (Bottom of right sidebar)
- 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
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
Once you generated some files for your new extension (and they are listed in the
file), you can include them into your Git based installation. Just:
# Change to the core directory of your installation:
# Install your new extension:
# Make sure the ownership of all files is still set correctly and according
# to the configuration of user and group of your webserver :
chown -R www-data:www-data .
For a trunk installation it might be required to configure apache, so it will support symlinks in
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!
git commit -m "Item2233: Checking in beta release of FooPlugin"
You want to see what has changed
since your last update? Check it!
You want to update your local copy
with the changes someone else did on some files?
8. Release your extension
To release it read on in BuildContrib