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

Last change on this file since 33258 was 33258, checked in by sjamaan, 5 years ago

hg-egg-author plugin moved

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