Preparing your source repository

You'll need a local feed within your source directory (under version control). This contains the same information as a normal published feed would (name, description, dependencies, etc). The only differences are:

• The local feed refers to a local directory (e.g. id="." for the directory containing the local feed) rather than a secure hash.
• It has no digital signature.
• The version will be a development version (e.g "1.2-post" if your last released version was "1.2").

Having a local feed is useful even if you don't use 0release, because it lets people check out a development snapshot of your program and then register it (using 0launch --feed) or run it directly with Zero Install handling its dependencies.

A minimal Hello World example is available for testing. You can check it out like this, using the GIT version control system:

$ git clone http://0install.net/tests/hello.git

To check that you can run it, use 0launch on the feed:

$ cd hello
$ 0launch HelloWorld.xml
Hello World!

HelloWorld.xml is the local feed. Its contents look like this:

<?xml version="1.0" ?>
<interface xmlns="http://zero-install.sourceforge.net/2004/injector/interface">
  <name>HelloWorld</name>
  <summary>minimal demonstration package for 0release</summary>
  <description>
    This program outputs the message "Hello World". You can create new releases of it
    using 0release.
  </description>

  <homepage>http://0install.net/0release.xml</homepage>

  <feed-for interface='http://0install.net/tests/HelloWorld.xml'/>

  <group main='hello.py'>
    <implementation id="." version="0.1-pre"/>
  </group>
</interface>

Note the <feed-for> element. This is where the main feed is (or will be) published. If you want to follow this tutorial, change it to point to a location to which you can upload files (e.g. "http://localhost/~me/testing/HelloWorld.xml") and commit the change (git commit -a).

You should add any dependencies inside the <group> element (see the feed specification for details, or edit the feed using 0publish-gui if you want a graphical interface). This example program is so simple it doesn't have any dependencies.

Creating the releases directory

Each time you create a new release, the resulting files go in your 'releases' directory. Create the directory now and then run 0release inside it, giving it the location of your local feed.

$ mkdir -p ~/releases/hello
$ cd ~/releases/hello
$ 0launch http://0install.net/2007/interfaces/0release.xml ~/hello/HelloWorld.xml
Setting up releases directory for HelloWorld
Success - created script:
 ~/releases/hello/make-release
Now edit it with your local settings.
Then, create new releases by running it.

This will create a single executable file in the directory, called make-release. Run this whenever you want to create a new release of your software.

• The make-release file contains local configuration information (e.g. the location of the local feed on your computer).
• General information about your program goes in the source directory so it can be shared by other developers.

Open the file in a text editor. There are five settings, with comments explaining what is needed. The only one you need to set is the first (ARCHIVE_DIR_PUBLIC_URL), which is where people will download the release from. In my case, I'll be uploading them to SourceForge so I set it to:

ARCHIVE_DIR_PUBLIC_URL=http://osdn.dl.sourceforge.net/sourceforge/zero-install

The other settings allow 0release to push files to the remote server automatically, but you can leave them as they are and do it manually if you prefer.

Creating a release candidate

When you want to make a new release, simply run the make-release script, like this:

$ cd ~/releases/hello
$ ./make-release
Releasing HelloWorld
Snapshot version is 0.1-pre
Version number for new release [0.1]:

You are prompted to enter the version number for the new release. You can just press Return to accept the default of 0.1 (since the version in the local feed was 0.1-pre). It then prints:

Releasing version 0.1
HEAD is now at a2d1ed9 Prints "Hello World" already!
SKIPPING unit tests for ~/releases/0.1/helloworld-0.1 (no 'self-test' attribute set)
Wrote source feed as helloworld-0.1.xml
Wrote changelog from start to here as changelog-0.1

Candidate release archive: helloworld-0.1.tar.bz2
(extracted to ~/releases/0.1/helloworld-0.1 for inspection)

Please check candidate and select an action:
P) Publish candidate (accept)
F) Fail candidate (untag)
(you can also hit CTRL-C and resume this script when done)
Publish/Fail:

0release has now created a candidate archive for you to examine. You might like to try running the program now. Note that the archive only contains files that are under version control.

You can either leave 0release running while you check it, or you can press CTRL-C to exit and run the make-release script again later. It will remember where it was (it stores the current status in a new release-status file).

As well as exporting the release archive, 0release also updates your GIT repository by committing two new revisions. You can see them using gitk --all:

The first revision (master) is the 0.1-pre development snapshot you started with. This is also the currently checked-out version. 0release has created a new branch called "0release-tmp" with two new revisions. "Release 0.1" is the version that will be released. Its local feed has the version "0.1" and today's date as the release date. The archive was created from this revision. The next revision has a version of "0.1-post" and removes the release date again. Note that the release hasn't been tagged yet in GIT, but 0release has recorded the revision ID in case you decide to accept the release candidate.

If you discover any problems you can go ahead and commit a fix, which will appear on the master branch (not on the "0release-tmp" branch, which will be discarded if you fail the release).

Accepting the release candidate

We'll just check that the release works:

$ 0launch 0.1/helloworld-0.1/HelloWorld.xml
Hello World!

Looks good. If you killed the release script (with CTRL-C), run it again now to return to the Publish/Fail prompt. Choose Publish (you can just type p<Return>).

The temporary files (release-status and the extracted helloworld-0.1 directory) are removed, and you will be prompted to enter your GPG passphrase to sign the release (use --key if you don't want to use the default key).

Tagged as v0.1
HEAD is now at 07f3c9e Start development series 0.1-post
Deleted branch 0release-tmp.
Changing key from 'None' to 'YOUR-KEY'
Exported public key as '~/releases/YOUR-KEY.gpg'

A new file then appears: HelloWorld.xml. This is the master feed for the program, which you should publish on your web-site. It will list all versions of the program (although currently it only contains one version, of course). Finally, you will also find a .gpg file containing your GPG public key.

If you check your GIT repository, you'll see that 0release has now tagged the release, and updated the "master" branch to the tip of the temporary branch:

If, instead, you had found a problem with the release you would have selected Fail at the prompt. 0release would have removed the temporary branch (leaving "master" where it was) and deleted the temporary files.

Uploading the files

If you didn't set an upload command in the make-release configuration file, 0release will prompt you to upload the files now:

Upload status:
- helloworld-0.1.tar.bz2 : Upload required

Upload 0.1/helloworld-0.1.tar.bz2 as http://osdn.dl.sourceforge.net/sourceforge/zero-install/helloworld-0.1.tar.bz2
No upload command is set => please upload the archive manually now
Press Return once the archive is uploaded.

Copy the files (helloworld-0.1.tar.bz2, HelloWorld.xml and <KEYID>.gpg) to your web-server. When you press Return, 0release will check that the archives were uploaded correctly:

Testing URL http://osdn.dl.sourceforge.net/sourceforge/zero-install/helloworld-0.1.tar.bz2...

Upload status:
- helloworld-0.1.tar.bz2 : Upload has been checked (exists and has correct size)

You should then be able to download and run the new release, using the URL you chose at the start:

$ 0launch http://localhost/~me/testing/HelloWorld.xml
Hello World!

Finally, it will prompt you to upload the feed and the new GIT commits:

Upload ~/releases/HelloWorld.xml into http://0install.net/tests
NOTE: No feed upload command set => you'll have to upload them yourself!
Push changes to public SCM repository...
NOTE: No public repository set => you'll have to push the tag and trunk yourself.

You can edit make-release to set some commands to automatically upload the files and to push the branch and tag ("master" and "v0.1" in this case) to your public GIT repository.

Customising the release process

For more information, see release phases.

Source and binaries

If your program needs to be compiled, see Releasing binaries.

Unpublishing a release

So, you didn't test the release properly, and now you want to pull it down, eh?

The best way to do this is to use 0publish-gui to set the stability to BUGGY, and then publish a new fixed release, with a new version number.

But if you really insist on trying to unpublish a release and pretending it never happened, here's what you have to do:

1. Edit the master feed (e.g. with 0publish-gui) and delete the new <implementation>. Don't just use a text editor; the signature needs updating too! Push the new version to your server.

   Note: if you keep your feed under version control then you could revert the change. However, if anyone got the new version before you reverted it, then 0launch will refuse to go back to the previous version, assuming that this is a replay attack. So create a new signature, with a fresh time-stamp.

2. Reset HEAD to before the release (e.g. "git-reset --hard v0.1^") and delete the tag itself (e.g. "git-tag -d v0.1"). Delete the remote tag at the server (e.g. "git-push main :v0.1 master"). Like 0launch, if anyone saw the release in GIT, their GIT will refuse to go back to an older version. Tell them to use '-f'.

3. Delete the tarball from your server.