source: project/wiki/releasing-your-egg @ 31434

Last change on this file since 31434 was 31434, checked in by sjamaan, 7 years ago

Update "releasing your egg" page to include major chicken release version (not yet required, but it is already accepted now)

File size: 23.0 KB
Line 
1== Releasing your egg
2
3[[toc:]]
4
5Let's say you've been reading the [[eggs tutorial]] and you are almost
6done writing your first egg.  You've tested that it works locally, and
7now you probably want to make it available to others.  If you would
8like people to be able to install your egg using {{chicken-install YOUR-EGG}},
9there are a few steps you need to take.
10
11=== Note for Subversion users
12
13If you host your egg on {{code.call-cc.org}} or you host your own,
14you don't ''have'' to do any of the steps below.  Instead, you can
15use the release generating script at call-cc.org.  It does all the
16steps below automatically.
17
18The URI for an automatically generated release-info for egg YOUR-EGG is
19{{http://code.call-cc.org/release-info?egg=YOUR-EGG}}
20
21This URI can be put in the {{egg-locations}} file as described under
22[[#publishing-your-egg|"Publishing your egg"]].
23
24If you want more control over the process, please read on.
25
26=== Creating a release-info file
27
28First, you must create a so-called "release-info" file and make it
29available on a well-known location via HTTP (discussed below).  This
30is a file which describes where the released versions of your egg can
31be found.
32
33After everything's set up, releasing a new version of your egg is
34simply a matter of tagging your release with your VCS of choice and
35adding a line to this file. See [[#helper-scripts|below]] for some tools
36to automate even this small step.
37
38It looks something like this:
39
40<enscript highlight="scheme">
41(repo git "git://example.com/{egg-name}.git")   ; optional
42
43(uri targz "http://example.com/{egg-name}/releases/{chicken-release}/{egg-name}-{egg-release}.tar.gz")
44(release "0.1")
45(release "0.2")
46(release "1.0")
47</enscript>
48
49This example describes where to find the canonical repository and an URI pattern
50which describes how to find release tarballs.  It then goes on to declare three
51official releases; 0.1, 0.2 and 1.0.
52
53The patterns in the URI enclosed in curly braces are seen as
54substitution patterns to be replaced by values.  {{egg-name}} expands
55to the current egg's name (which is already known when the
56release-info file is being fetched), {{egg-release}} is replaced by
57the string in each {{release}} declaration.  {{chicken-release}} is
58replaced by the major CHICKEN version for which the egg is being
59fetched.  This allows you to supply different packages for each major
60CHICKEN release.
61
62The supported types for {{uri}} are currently {{targz}}, {{tarbz2}}, {{zip}},
63{{meta-file}} and {{files-list}}.  The first three are all archives expected
64to extract to a directory with the egg sources in it (zip files are allowed
65to expand directly into the files, but this is not recommended).  The latter
66two are special and deserves some more explanation; see the next section for that.
67
68Currently {{repo}} is not used by automated tools, but is intended to
69make it easy for users to find the repository.  In preparation for
70when it will be used in the future, it's a good idea to use consistent
71names, so please use the ''short name'' of the tool.  Generally this is
72how it is invoked on the commandline: {{svn}}, {{mtn}}, {{git}},
73{{bzr}}, {{hg}}, {{darcs}}, {{fossil}} etc.
74
75==== Meta-file distribution
76
77Sometimes it is impractical to create archives containing your egg's file
78contents.  The egg releasing system has been designed to require as few manual
79steps as possible, so it is easy for people to release early and often.
80
81A core ideal of the release system is to make it possible to release
82simply by tagging your code in a VCS.  Some code hosting sites
83automatically make archives available for each tagged version, thereby
84making the release available immediately when the code is pushed to
85the server.  For those that don't, the meta-file distribution file
86type is a way to release by tagging ''without'' having to manually
87make a tarball, ''as long as there is a way to directly obtain the raw
88sources of a specific release version via HTTP''.
89
90The idea is that each released egg always must have a meta-file to describe
91its dependencies, its author and license and so on.  This meta-file can be
92used to provide a listing of all the files that are part of an egg.  The system
93that manages egg releases automatically will download all these files and put
94them in a directory.  When someone requests your egg with {{chicken-install}},
95these files are all served up.  Just add a {{files}} entry to your meta-file,
96which lists the files (these are resolved relatively to the meta-file itself).
97
98<enscript highlight="scheme">
99((files "uri-common.setup" "uri-common.release-info" "uri-common.meta"
100        "uri-common.scm" "tests/run.scm")
101 (license "BSD")
102 (category web)
103 (depends (uri-generic 2.3) defstruct matchable)
104 (test-depends test)
105 (author "Peter Bex")
106 (synopsis "Parser for common URI schemes"))
107</enscript>
108
109This is a real-world example of the [[/eggref/4/uri-common|uri-common egg]].
110It lists all the files which it consists of, and these will be downloaded by
111chicken-install.  The disadvantage of this approach is that if you forget a
112file, your egg is uninstallable, so if you can please use the archive
113distribution types instead.  Another disadvantage is that every time you add,
114remove or rename a file you need to remember to change the meta-file.
115
116The {{uri}} entry in uri-common's {{release-info}} file looked like this
117before there was an autogenerated one:
118
119<enscript highlight="scheme">
120(uri meta-file "http://anonymous@code.call-cc.org/svn/chicken-eggs/release/{chicken-release}/{egg-name}/tags/{egg-release}/{egg-name}.meta")
121</enscript>
122
123Because this egg uses subversion and each release has a corresponding
124tag, it can simply point to the metafile in the right subdirectory
125under tags and it will simply work.  For other version systems this
126may require some more messing around.
127
128==== files-list
129
130This is an extremely stupid format containing a manifest of files in
131an egg.  It's mostly useful when automatically generating lists of files.
132It starts with a base URI and then lists all the files in the egg.
133Here's the [[http://code.call-cc.org/files-list?egg=uri-generic;egg-release=1.0;chicken-release=4|files-list for version 1.0 of the uri-generic egg for CHICKEN 4]]:
134
135  http://anonymous:@code.call-cc.org/svn/chicken-eggs/release/4/uri-generic/tags/1.0
136  tests/run.scm
137  uri-generic.meta
138  uri-generic.scm
139  uri-generic.setup
140
141The trailing slash after the URI is required.
142
143It's not recommended you use this manually, as this format is subject
144to change and only really intended to be used as a communication system
145between [[/eggref/4/pseudo-meta-egg-info|pseudo-meta-egg-info]] and
146[[/eggref/4/henrietta-cache|henrietta-cache]].
147
148However, if you really need to use this, you can replace the
149{{meta-file}} uri type in the example above by {{files-list}}, like
150the auto-generated
151[[http://code.call-cc.org/release-info?egg=uri-generic|release-info file for uri-generic]],
152which starts like this:
153
154  (uri files-list "http://code.call-cc.org/files-list?egg={egg-name};egg-release={egg-release};chicken-release={chicken-release}")
155  (release "1.0")
156  (release "1.1")
157
158=== Publishing your egg
159
160After creating the release-info file, you need to make it known to the
161chicken-install infrastructure that an egg with the given name has a
162release info file at the location where you published it.  This step finally
163makes it possible for people to say {{chicken-install YOUR-EGG}} and have
164it install your egg, or use {{(depends YOUR-EGG)}} in meta-files of their eggs.
165
166Currently this is done by adding a line to the egg-locations file in
167Subversion, which can be found at
168[[https://code.call-cc.org/svn/chicken-eggs/release/4/egg-locations]]. For security reasons, editing the {{egg-locations}} file requires special permissions.  So, to have an entry for your egg in that file, send a message to the [[http://lists.nongnu.org/mailman/listinfo/chicken-users|chicken-users mailing list]] announcing your egg and requesting the inclusion of its location to {{egg-locations}}.
169
170To keep maintenance to a minimum, it's best to add a release-info
171location which will never change; only the release-info file itself
172should be changed when you make a new release.  This can most easily
173be accomplished by pointing to the "raw file" view of your
174trunk/tip/head/master branch in your canonical repository's web
175interface.  That way, this file is kept under version control
176alongside all the other files in your egg.
177
178If you do have an svn account and don't want to checkout the whole egg
179repository to be able to just edit this file, you can work around svn's
180limitations like this:
181
182 $ cd /tmp
183 $ svn co https://code.call-cc.org/svn/chicken-eggs/release/4 --depth empty
184 $ cd 4
185 $ svn update egg-locations
186
187If you prefer, you can just publish the file separately via HTTP
188somewhere and keep overwriting it.  If your code hoster doesn't
189provide an easy way to point to a raw view on a moving "latest
190version" pointer via HTTP, you could instead opt to store just the
191release-info files of your eggs in the centralised CHICKEN eggs
192subversion repository.  Just contact one of the project maintainers or
193write to the chicken-users mailinglist.
194
195=== Instructions for popular code hosting methods and VCSes
196
197Now we've explained the basic idea, here's an overview of how to figure
198out the correct URIs and how to automate some steps away.
199
200==== CHICKEN subversion eggs repository
201
202The traditional way to distribute eggs has not changed much.  We hope
203to get rid of the manual steps by writing post-commit hooks but for
204now it is necessary to maintain a meta-file listing all the files in
205your egg and to create a release-info file containing all your
206tags and the following repo and uri entries:
207
208<enscript highlight="scheme">
209(repo svn "http://anonymous@code.call-cc.org/svn/chicken-eggs/release/4/{egg-name}")
210(uri meta-file "http://anonymous@code.call-cc.org/svn/chicken-eggs/release/4/{egg-name}/tags/{egg-release}/{egg-name}.meta")}}
211</enscript>
212
213You can copy these verbatim.  For existing eggs we've already done the
214work for you.
215
216==== Bitbucket (mercurial)
217
218===== Location of release-info file
219
220You can use the code browser to figure out the path to your
221release-info file.  First, copy the link that says "raw".  This URI is
222almost correct but will contain a revision ID hash, so it is pinned to
223whatever revision is currently the tip.  However, you can replace it
224with the string "tip" and it will still work, and when you visit it again
225after making changes it will have picked up those changes.  Example:
226
227Clicking "spiffy.release-info" and then copying the "raw" link on
228[[https://bitbucket.org/sjamaan/spiffy/src]] gives us
229[[https://bitbucket.org/sjamaan/spiffy/raw/d370bdd7ecf8/spiffy.release-info]]
230
231Just change it to
232[[https://bitbucket.org/sjamaan/spiffy/raw/tip/spiffy.release-info]]
233and you have the latest tip.  This link should be registered in the
234egg-locations list for your egg and it will automatically be able to
235fetch any new releases as they are tagged and added to the
236release-info file.
237
238===== Making releases
239
240The bitbucket code browser also offers a "get source" link that allows
241you to fetch the files in that revision as a tarball.  The same trick
242as with the raw files works here; just replace the link's revision ID
243hash with a symbolic name.  You can use tags and bookmarks as symbolic
244names.
245
246So to make a new release, just tag your release with a well-defined
247name. If you tag your eggs with the version as tag or bookmark name,
248you can use the following release-info file.  Just don't forget to
249substitute your bitbucket username!
250
251<enscript highlight="scheme">
252(repo hg "https://bitbucket.org/YOUR-BITBUCKET-USERNAME/{egg-name}")
253(uri targz "https://bitbucket.org/YOUR-BITBUCKET-USERNAME/{egg-name}/get/{egg-release}.tar.gz")
254(release "0.1")
255</enscript>
256
257==== Gitorious (git)
258
259===== Location of release-info file
260
261Use the code browser (the "Source tree" button) to browse to your
262master branch's release-info file and copy the "Raw blob data" link.
263For example, for the [[/eggref/4/ssql|ssql egg]] it would look like:
264
265[[https://gitorious.org/chicken-eggs/ssql/raw/master:ssql.release-info]]
266
267===== Making releases
268
269Gitorious makes tags available for download as tarballs.  To find the
270location, go to the source tree browser and switch to a tag in the
271right-hand panel. You should now get a button in the same panel that
272says "Download TAG-NAME as tar.gz".
273
274So to make a new release, just tag your release with a well-defined
275name. If you tag your eggs with the version as tag name, you can use
276the following release-info file.  Just don't forget to substitute your
277Gitorious project name!
278
279<enscript highlight="scheme">
280(repo git "git@gitorious.org:PROJECT-NAME/{egg-name}.git")
281(uri targz "https://gitorious.org/PROJECT-NAME/{egg-name}/archive-tarball/{egg-release}")
282(release "0.1")
283</enscript>
284
285Note that there is a [[https://gitorious.org/chicken-eggs|CHICKEN Eggs
286project]] on Gitorious already. If you want you can ask its owner to
287add your egg's repository to it.
288
289==== Github (git)
290
291===== Location of release-info file
292
293Use the code browser ("source" tab) to browse to your release-info
294file and copy the "raw" link.  This link should work as-is, as long as
295you do this while looking at the latest revision of the file in the
296master branch.  For example, for the [[/eggref/4/kalaha|Kalaha egg]]
297it would look like:
298
299[[https://raw.github.com/DerGuteMoritz/kalaha/master/kalaha.release-info]]
300
301===== Making releases
302
303Github makes tags available for download as tarballs.  To find the
304location, click the big "Downloads" button/link in the code browser.
305It will pop up a selection dialog where you can choose between tarball
306and "zipball".  It will also offer downloads for each tag, but those
307are zipballs only.  However, you can copy the link and replace
308"zipball" in the URL by "tarball", or you can first click "switch
309tags" and then open the "Downloads" dialog and it will offer you
310download links for both tar and zip for that specific tag.
311
312So to make a new release, just tag your release with a well-defined
313name. If you tag your eggs with the version as tag name, you can use
314the following release-info file.  Just don't forget to substitute your
315Github username!
316
317<enscript highlight="scheme">
318(repo git "git://github.com/YOUR-GITHUB-USERNAME/{egg-name}.git")
319(uri targz "https://codeload.github.com/YOUR-GITHUB-USERNAME/{egg-name}/tar.gz/{egg-release}")
320(release "0.1")
321</enscript>
322
323==== Google Code (mercurial, subversion)
324
325The location of files in Google code is mostly similar for subversion
326and mercurial, so we're discussing them in one go.
327
328===== Location of release-info file
329
330On the "source" tab, click "browse" and visit the release-info file.
331Ensure that you didn't click any revision numbers, otherwise it will
332remember the specific revision you clicked, ''even if that was the
333latest''.  Look for the link that says "raw" and copy it.  It should
334look something like [[http://my-egg.googlecode.com/hg/my-egg.release-info]]
335for Mercurial or [[http://my-egg.googlecode.com/svn/trunk/my-egg.release-info]]
336for Subversion.
337
338===== Making releases
339
340Google Code currently does not have a way to automatically serve up
341tagged revisions as tarballs.  They have also
342[[http://google-opensource.blogspot.com/2013/05/a-change-to-google-code-download-service.html|shut down]]
343the ability to host custom downloads, so right now the only way to
344host eggs on Google Code is by listing all the files in your egg
345in its meta-file.  See [[#meta-file-distribution|the meta-file section]]
346at the start of this wiki page to figure out how to set up a {{files}}
347section in your meta-file.
348
349When you have the list set up in your meta-file, you can then point to
350it from your release-info file.
351
352For Mercurial, you can base your release-info file off the following
353snippet:
354
355<enscript highlight="scheme">
356(repo hg "https://my-egg.googlecode.com/hg/")
357(uri meta-file "http://my-egg.googlecode.com/hg/{egg-name}.meta?r={egg-release}")
358(release "0.1")
359</enscript>
360
361For Subversion, you can use this snippet:
362
363<enscript highlight="scheme">
364(repo svn "http://my-egg.googlecode.com/svn/")
365(uri meta-file "http://my-egg.googlecode.com/svn/tags/{egg-release}/{egg-name}.meta")
366(release "0.1")
367</enscript>
368
369==== hgweb (mercurial) - aka "hg serve"
370
371The built-in web interface for mercurial can be used to serve up eggs,
372usually invoked from hgweb and hgwebdir on a "real" server.
373
374===== Location of release-info file
375
376Use the browser to navigate to the latest revision of the release-info
377file and click the "raw" link on the left.  Then replace the commit ID
378hash with "tip".  Example:
379
380[[http://example.com/my-egg/raw-file/tip/my-egg.release-info]]
381
382===== Making releases
383
384Since this interface doesn't have a way to serve up tarballs, you must
385either create your own tarballs and publish them elsewhere or use the
386manual "meta-file" way.
387
388See [[#meta-file-distribution|the meta-file section]] at the start of
389this wiki page to figure out how to set up a {{files}} section in your
390meta-file.  The URI to your meta file is similar to the release-info
391file, except this time you can replace "tip" with the release's
392tagname.  If you use tagnames that are identical to the release
393version, you can base the release-info file on the following example:
394
395<enscript highlight="scheme">
396(repo hg "http://example.com/{egg-name}")
397(uri meta-file "http://example.com/{egg-name}/raw-file/{egg-release}/{egg-name}.meta")
398(release "0.1")
399</enscript>
400
401This assumes hgwebdir is running on the domain's root URI and the egg
402is available in a repo which has the same name as your egg.
403
404==== Fossil's default web UI
405
406This is the web UI you get when running "fossil serve" or when running
407fossil as a CGI script.
408
409There is one tricky part: by default, this interface disallows almost
410all outside access; you ''must'' log in, even if you just want to
411browse anonymously. To allow everybody to download release zipfiles or
412tarballs without login, add the "z" permission for the user "nobody"
413in the Admin / Users section of the web UI or with the "fossil user
414capabilities" command.
415
416===== Location of release-info file
417
418Fossil's web UI allows serving of documents directly from the
419repository under URLs of the form
420"http://example.com/my-egg/doc/{version}/{file}". If the files have a
421".txt" or ".wiki" extension, they are rendered into HTML, but anything
422else is served as is.
423
424For example you can store the release-info file in the repository and
425always access the latest version of the default branch at a URL like
426"http://example.com/my-egg/doc/trunk/my-egg.release-info".
427
428===== Making releases
429
430Fossil can serve tarballs or zipfiles of repository snapshots. A
431release-info file using zipfile packaging may look like this:
432
433<enscript highlight="scheme">
434(repo fossil "http://example.com/{egg-name}")
435(uri zip "http://example.com/{egg-name}/zip/{egg-name}.zip?uuid=v{egg-release}")
436(release "1.0.0")
437</enscript>
438
439For tarball packaging, the equivalent {{uri}} entry should look like
440this:
441
442<enscript highlight="scheme">
443(uri targz "http://example.com/{egg-name}/tarball/{egg-name}.tar.gz?uuid=v{egg-release}")
444</enscript>
445
446The releases are referenced using symbolic tags of the form
447"v{egg-release}" here. You can add these tags to the changesets
448corresponding to released versions of the egg using the "fossil tag
449add" command.
450
451==== Launchpad (bazaar)
452
453Unfortunately, Launchpad doesn't currently seem very suitable for
454developing eggs in a streamlined way.  Here's a description of one
455possible way to integrate with their way of doing release management though.
456
457===== Location of release-info file
458
459You can browse to the release-info file using Loggerhead (the web
460interface to bazaar), but there doesn't seem to be a reliable way to
461construct a raw download URI for "the latest version of" a file.
462
463A workaround is to create a release series just for the release-info,
464and make an (unused) milestone for that.  Then you can upload a
465release-info file.  The URI that's listed directly on the downloads
466page is stable though (something like
467[[http://launchpad.net/my-project/main/release-info/+download/my-egg.release-info]]
468if you named the milestone "release-info" in the "main" series)
469This link redirects to an unstable URI, so don't paste that one!
470
471When you make a new release you can ''delete'' the file and upload a new
472one manually to the same pseudo-"release".
473
474
475===== Making releases
476
477If you do it through their release management, you just create release
478tarballs which you manually upload into the release milestone.
479
480The only automation here is that you can use {{bzr export --format=tgz}}
481to create it, and the advantage that you're using someone else's site to
482host your code.
483
484You can use this release-info file template if you are consistent in
485your milestone naming.  It assumes you used the name "main" for the
486series from which releases for chicken-install are made.  You could
487alternatively add several {{uri}} entries, one per series, but it's
488still required that your egg's release versions are unique for your
489egg.  Series are probably more suitable for distinguishing between
490major CHICKEN release versions.
491
492<enscript highlight="scheme">
493(repo bzr "lp:MY-PROJECT/main")
494
495(uri targz "http://launchpad.net/MY-PROJECT/main/{egg-release}/+download/{egg-name}.tar.gz")
496(release "0.1")
497(release "0.2")
498</enscript>
499
500
501=== Helper scripts
502
503To make life easier, there are some helper scripts, hooks etcetera
504that could be used.  Please add your own links here.
505
506==== Subversion
507
508There's an [[/eggref/4/svn-egg-author|svn-egg-author egg]] that helps
509you to update the release-info and meta files and tag a release of
510your egg, all with one command.
511
512If you run your own subversion server with Spiffy, you can consider
513using [[/eggref/4/pseudo-meta-egg-info|pseudo-meta-egg-info]] instead.
514If you do, you do not need to use svn-egg-author.  If you're using the
515chicken-eggs repository hosted on call-cc.org, you don't need it either
516because call-cc is already running pseudo-meta-egg-info for all its eggs.
517
518==== Mercurial
519
520There's an
521[[https://bitbucket.org/sjamaan/egg-author/src/tip/egg-author.py|egg-author]]
522extension for Mercurial that allows you to say {{hg eggtag 0.1}} and have it
523automatically update the release-info file with the new tag name.
524
525==== Git
526
527There's a [[/eggref/4/git-egg-author|git-egg-author egg]] that helps you
528keep your release-info file up-to-date and tag a release with one command.
529
530==== Bazaar
531
532There's also a [[https://launchpad.net/bzr-egg-author|bzr-egg-author]]
533extension for Bazaar that allows you to say {{bzr eggtag 0.1}} and have it
534automatically update the release-info file with the new tag name.
535
536=== Moving an egg
537
538When you decide to migrate to a different code hosting site, and don't
539want to move all releases, you can define multiple uris:
540
541<enscript highlight="scheme">
542;; Main ("default") repo
543(repo hg "https://bitbucket.org/YOUR-BITBUCKET-USERNAME/{egg-name}")
544(uri targz "https://bitbucket.org/YOUR-BITBUCKET-USERNAME/{egg-name}/get/{egg-release}.tar.gz")
545(release "2.1")
546(release "2.0")
547
548;; Old repo, using "old-svn-repo" alias
549(repo svn "http://anonymous:@code.call-cc.org/svn/chicken-eggs/release/4/{egg-name}")
550(uri files-list "http://code.call-cc.org/files-list?egg={egg-name};egg-release={egg-release};chicken-release={chicken-release}" old-svn-repo)
551(release "1.3" old-svn-repo)
552(release "1.2" old-svn-repo)
553(release "1.1" old-svn-repo)
554(release "1.0" old-svn-repo)
555(release "0.2" old-svn-repo)
556(release "0.1" old-svn-repo)
557</enscript>
Note: See TracBrowser for help on using the repository browser.