This document describes in some small amount of detail the mpwa. Goals: - Develop a network-reachable port storage mechanism - Allow for ad-hoc submission of new ports/revisions by any user - Since users may submit ports and make them available, port availability is not held up for review by committers. Committers may provide special status to approved ports. - 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 a 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 (portpkg) to be submitted over the network through an http transaction. - Each submitted portpkg is given a unique network-readable url and directory structure - The directory created for each submitted portpkg 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 information, etc). Additional: - Unique portpkg 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/instances 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 might also provide ways to query for ports based on other criteria, such as the number of reported build failures for the port, generic "votes" for or against the port, etc. - 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. - Note that portpkg submission is final, unequivocal, and stable. Once a submission is made and assigned a pkgid/pkgurl, it may not be edited. Any changes to the portpkg require a new submission. The same is not true for some of the metadata about a portpkg which may be changed (comments, build status, tags, stable, etc). Nomenclature: - "port": Generically, a set of build instructions and/or resultant binaries for a given piece of software. Multiple sets of such build instructions may (and probably do) exist for any port, accounting for such things as changes in software version, build procedures, etc. - "portpkg": A particular set of build instructions for a given port. This includes the bundled set of the files that this requires: Portfile + /files and any other relevant metadata or contents of the port directory. - "pkgid": The unique id assigned to the submission of a portpkg at db.macports.org. - "pkgurl": a url that uniquely references a portpkg. This is probably formed in part from the pkgid. Issues: - 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 pkgurl as a unique portpkg descriptor - n portpkgs for each port (even including potentially multiple portpkgs per epoch-version-revision) - tags - flags - Perhaps the pkgid begins to supplant or replace the port revision? So that for two ports at the same version, the one with the higher pkgid wins, all else being equal? - What does it mean to flag a port as stable? Is there only one such designation per port? Once a port instance is flagged as stable, does the previous such stable port version lose that designation? Or is it possible to determine that a portpkg was previously stable? And if so, that brings up the need to be able to determine the "latest stable" portpkg of a port? Is stable, or whatever, simply a privileged tag, such that one has to have special rights to apply it, but it can be attached to as many portpkgs of a port as needed? - Though we provide a network-accessible location and unique urls for portpkgs, we should not restrict the ability to install an http:scheme portpkg only from this repository. The port command should be able to install any properly formatted portpkg given a url to the portpkg. (In other words, any url http://someurl that returns a properly formatted portpkg should be installable, whether or not it is hosted at macports). - Should the actions below be added to the port command, or should an additional wrapper be created? Potential public urls for ports: // primary access to portpkg // This url returns the portpkg, not a human readable page http://db.macports.org/portpkg/ // Access to portpkg files http://db.macports.org/portpkg// // Submittal url // Form to submit a portpkg http://db.macports.org/submit // A portpkg defined by a query instead of a pkgid // (will 301 redirect to http://db.macports.org/portpkg/) http://db.macports.org/portpkg/latest/ http://db.macports.org/portpkg/stable/ // Pages with human readable html content http://db.macports.org/category/ (ports by category) http://db.macports.org/tag/ (ports by tag) http://db.macports.org/port/ (port by name) http://db.macports.org/pkgid/ (portpkg by pkgid) Issues for urls: - If a port is installed using a url that does a 301 (permanent) redirect to another port, the url remembered as the installed port should be the redirected target, rather than the original. This would allow the url for a stable version of a port to redirect to the particular portpkg to which it resolves, and yet maintain a one-to-one mapping between url and port. ====== Potential port(1) Actions: port submit ==> portpkg ==> submission meta information, generically ==> submitter ==> portpkg digest (potentially signed by submitter) <== status <== pkgurl -- Make a port submission port query ==> portname <== pkgurls (with additional meta? flags, tags, submitter, date, version, revision, status?) -- Query portpkgs port flag_stable pkgurl -- Promote a given portpkg to stable status (requires authentication) port submitreport ==> pkgurl ==> report data (??? tbd) -- Submit a report for a given portpkg port showreports ==> pkgurl <== reports (??? tbd ...urls to the reports? or text?) -- Query reports for a given port submission port get ==> pkgurl <== portpkg -- Bring a given portpkg into the local collection (or cache?) or portpkgs Document TODO: