[23527] users/jberry/mpwa/doc/design.txt
source_changes at macosforge.org
source_changes at macosforge.org
Tue Apr 3 16:34:07 PDT 2007
Revision: 23527
http://trac.macosforge.org/projects/macports/changeset/23527
Author: jberry at macports.org
Date: 2007-04-03 16:34:06 -0700 (Tue, 03 Apr 2007)
Log Message:
-----------
Add mpwa design document with some details, layout, and lots of issues for discussion.
Added Paths:
-----------
users/jberry/mpwa/doc/design.txt
Added: users/jberry/mpwa/doc/design.txt
===================================================================
--- users/jberry/mpwa/doc/design.txt (rev 0)
+++ users/jberry/mpwa/doc/design.txt 2007-04-03 23:34:06 UTC (rev 23527)
@@ -0,0 +1,161 @@
+This document describes in some small amount of detail the on-disk storage
+for port submissions.
+
+Goals:
+
+ - Develop a network-reachable port storage mechanism
+
+ - Allow for ad-hoc submission of new ports/revisions by any user
+
+ - All submissions and versions should always remain network reachable
+ so that old versions may be installed and/or reviewed.
+
+ - Allow for storage of meta information with such a submission:
+ - Submitter
+ - Comments by various users
+ - Build status
+ - (potentially binaries)
+ - etc.
+
+ - Allow for promotion of such a submission to into special status (stable, whatever)
+ by the port maintainer or other official personnel.
+
+Thus:
+
+ - We begin to implement port "submit" which allows a port-directory structure
+ to be submitted over the network through an http transaction.
+
+ - Each such "submission" is given a unique network-readable url and directory structure
+
+ - Each submission is committed to the subversion repository.
+ (the submission id is formed partially from the subversion revision, but that is
+ an implementation detail).
+
+ - The directory created for each port submission contains the originally submitted
+ compressed directory structure, an unpacked version of the same, and a meta directory
+ that might contain other meta information (comments, build reports, build status, submitter, etc).
+
+Additional:
+
+ - Unique port submissions may be "flagged" with additional flags such as "stable".
+ (only one such flagged submission for any port? see issue below.).
+ (I'm using "flagged" to differentiate those actions which might be applied to only
+ one submission of a given port, versus "tagged" which could potentially apply
+ to multiple submissions of a given port. I'm not sure this differentiation is
+ applicable, appropriate, accurate, or even useful.)
+
+ - We might support arbitrary tags for ports, which would be a way of escaping the
+ single category hierarchy and provide users a means of building other meaningful
+ lists of ports.
+
+ - We now begin to have the ability to search for ports by additional criteria.
+ Not just the version, but whether they are stable or not, how they are tagged,
+ and even perhaps additional things such as the reputation of the submitter or
+ how popular they are. Social ports.
+
+Nomenclature:
+
+ - "submissionid": A unique id given to a submitted port.
+ Tried to stay away from port "version" or "revision", since
+ those are already used. "portid" might make sense as well.
+
+ - "porturl": a url that uniquely references a submitted port.
+ This is probably formed in part from the submissionid.
+
+Storage layout within the macports repository:
+
+ /port/submissions/catname/portname
+ /common/<unpacked directory tree> (revisioned/shared between submissions of the port)
+ /<submissionid>
+ /port.tgz (the submitted tarred-up port tree)
+ /unpacked/<directory tree>
+ /meta/
+ /submission_info
+ /comments (user comments?)
+ /reports (build logs?)
+ /status (build status?)
+ /binaries (potential future expansion)
+
+Issues:
+
+ - Call it a submissionid or a portid? (perhaps it doesn't matter, as it's really
+ just an internal number that becomes part of the public porturl, which is what
+ people really use).
+
+ - It is not determined yet to what degree port meta information should be stored
+ in the database vs in the submission directory. It's likely that much such
+ metadata (flags, tags, version, etc) should be at least shadowed into the
+ database. Some port information (such as comments or build reports) might
+ live well only in the directory, and not in the database.
+
+ - The package/archive format to use for ports is not yet determined (though .tgz
+ is used currently). zar might be good, though it will mean more work on tiger.
+
+ - We may need a means to build and/or fetch a local repository of the
+ port information for local use by the user, though we might be able to live
+ only with over-the-wire queries of the database. In any event, certain decisions
+ made here will effect the local repository design:
+ - The porturl as a unique port descriptor
+ - n submissions of each port (even including potentially multiple
+ submissions per epoch-version-revision)
+ - tags
+ - flags
+
+ - The porturl (and our on-disk structure) currently uses/requires the category/portname
+ subtree hierarchy. In some ways this is nice as it provides a simple human readable
+ discriminator and allows the leaf node for each port to contain the submissionids.
+ If we went to a flat structure for such urls (http://port.macports.org/portid) we could
+ escape the need for category and yet still store the submissions in whatever internal
+ form we liked. This would mean that the repository layout would match the port url,
+ which is perhaps a good thing, and it would mean that the we need some other means of
+ subsetting the internal organization of port submissions to avoid overloading the
+ directory structure.
+
+ - What does it mean to flag a port as stable? Is there only one such designation per port?
+ Once a submission is flagged as stable, does the previous such such stable port version
+ lose that designation? Or is it possible to determine that a port submission was previously
+ stable? And if so, that brings up the need to be able to determine the "latest stable"
+ submission of a port?
+
+ - Though we provide a network-accessible location and unique urls for ports, we should not
+ restrict the ability to install an http:scheme port to only this repository. The port command
+ should be able to install any properly formatted port given a url to the port data package.
+ (In other words, any url http://someurl that returns a properly formatted port package should
+ be installable, whether or not it is hosted at macports).
+
+======
+
+
+Actions:
+
+ port submit
+ ==> category
+ ==> portname
+ ==> portpackage
+ ==> info
+ <== status
+ <== porturl
+ -- Make a port submission
+
+ port submissions
+ ==> portname
+ <== porturls (with additional meta? flags, tags, submitter, date, version, revision, status?)
+ -- Query port submissions
+
+ port flag_stable porturl
+ -- Promote a given port submission to stable status (requires authentication)
+
+ port submitreport
+ ==> porturl
+ ==> report data (??? tbd)
+ -- Submit a report for a given port submission
+
+ port showreports
+ ==> porturl
+ <== reports (??? tbd ...urls to the reports? or text?)
+ -- Query reports for a given port submission
+
+ port fetch
+ ==> porturl
+ <== portpackage
+ -- Bring a given port into the local collection (or cache?) or ports
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20070403/5a173f66/attachment.html
More information about the macports-changes
mailing list