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/<pkgid>
		
			// Access to portpkg files
		http://db.macports.org/portpkg/<pkgid>/<path_to_file>
		
			// 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/<pkgid>)
		http://db.macports.org/portpkg/latest/<portname>
		http://db.macports.org/portpkg/stable/<portname>
		
			// Pages with human readable html content
		http://db.macports.org/category/<category>	(ports by category)
		http://db.macports.org/tag/<tags>			(ports by tag)
		http://db.macports.org/port/<portname>		(port by name)
		http://db.macports.org/pkgid/<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:
