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

Last change on this file since 31126 was 31126, checked in by Mario Domenech Goulart, 7 years ago

Properly capitalize CHICKEN on the wiki directory (only first level).

I used the following shell script to change things:

while IFS= read -d $'\0' -r file ; do

sed -i 's/Chicken/CHICKEN/g' "$file"

done < <(find wiki -maxdepth 1 -type f -print0 )

Some files have been manually reverted after that, since some
substitutions don't apply:

  • friedly-chicken (repl banner)
  • survey2011 (Chicken in URI paths)
  • chickenista-guide (Chickenista)

I hope the link canonicalization thing will be on my side.

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