[23625] users/jberry/mpwa/doc/design.txt

source_changes at macosforge.org source_changes at macosforge.org
Thu Apr 5 11:59:31 PDT 2007


Revision: 23625
          http://trac.macosforge.org/projects/macports/changeset/23625
Author:   jberry at macports.org
Date:     2007-04-05 11:59:31 -0700 (Thu, 05 Apr 2007)

Log Message:
-----------
Make additional nonemclature changes and clarifications to mpwa design doc.

Modified Paths:
--------------
    users/jberry/mpwa/doc/design.txt

Modified: users/jberry/mpwa/doc/design.txt
===================================================================
--- users/jberry/mpwa/doc/design.txt	2007-04-05 18:49:40 UTC (rev 23624)
+++ users/jberry/mpwa/doc/design.txt	2007-04-05 18:59:31 UTC (rev 23625)
@@ -25,23 +25,23 @@
 	
 Thus:
 	
-	- We begin to implement port "submit" which allows a port-directory structure
+	- 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 port is given a unique network-readable url and directory structure
+	- Each submitted portpkg is given a unique network-readable url and directory structure
 
-	- Each submitted port is committed to the subversion repository.
-	  (the submitted port id is formed partially from the subversion revision, but that is 
+	- Each submitted portpkg is committed to the subversion repository.
+	  (the pkgid is formed partially from the subversion revision, but that is 
 	  an implementation detail).
 
-	- The directory created for each submitted port contains the originally submitted
+	- 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 port submissions may be "flagged" with additional flags such as "stable".
+	- 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
@@ -54,17 +54,17 @@
 	
 	- 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, or perhaps the reputation of the submitter.
+	  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 port submission is are final, unequivocal, and stable. Once a submission is
-	  made and assigned a portid/porturl, it may not be edited. Any changes to the
-	  port require a new submission. The same is not true for some of the metadata about
-	  a submitted port which may be changed (comments, build status, tags, stable, etc).
+	- 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:
 
@@ -73,25 +73,24 @@
 		probably do) exist for any port, accounting for such things as changes
 		in software version, build procedures, etc.
 	
-	- "port instance": A particular set of build instructions for a given port.
-	
-	- "portpkg": The bundled set of the files that make up a port instance: Portfile + /files
-		and any other relevant contents of the port directory.
+	- "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.
 
-	- "portid": The unique id assigned to the submission of port instance/portpkg at db.macports.org.
+	- "pkgid": The unique id assigned to the submission of port portpkg at db.macports.org.
 		
-	- "porturl": a url that uniquely references a portpkg.
-		This is probably formed in part from the portid.
+	- "pkgurl": a url that uniquely references a portpkg.
+		This is probably formed in part from the pkgid.
 		
 Storage layout within the macports subversion repository:
 
 	/port/common (revisioned/shared between instances of a port)
 		/first-letter-of-portname
 			/portname/<directory tree> (the unbundled/uncompressed portpkg)
-	/port/instances
-		/5-low-bits-instance-id-2char-hex
-			/5-next-bits-instance-id-2char-hex
-				/instance-id-zero-padded-dec
+	/port/portpkgs
+		/5-low-bits-pkgid-2char-hex
+			/5-next-bits-pkgid-2char-hex
+				/pkgid-zero-padded-dec
 					/portpkg.tgz (the bundled/compressed portpkg)
 					/unpacked/<directory tree> (the unbundled/uncompressed portpkg)
 					/meta
@@ -104,49 +103,39 @@
 Issues:
 
 	- It is not determined yet to what degree port meta information should be stored
-	  in the database vs in the instance directory. It's likely that much such
+	  in the database vs in the portpkg 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). xar might be good, though it will mean more work on tiger.
+	  is used currently). xar is a likely a good choice, 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/instances of each port (even including potentially multiple 
-		  instances per epoch-version-revision)
+		- The pkgurl as a unique port descriptor
+		- n submissions/portpkgs of each port (even including potentially multiple 
+		  portpkgs per epoch-version-revision)
 		- tags
 		- flags
 		
-	- Perhaps the portid begins to supplant or replace the port revision? So that for two ports
-	  at the same version, the one with the higher portid wins, all else being equal?
+	- 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?
 		
-	- 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 portids.
-	  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 no longer match the port url,
-	  which is perhaps a good thing, and it would mean that 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 port instance is flagged as stable, does the previous such stable port version
-	  lose that designation? Or is it possible to determine that a port instance was previously
+	  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"
-	  instance 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 instances
+	  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 ports, we should not
-	  restrict the ability to install an http:scheme port only from 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
+	- 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
@@ -156,18 +145,18 @@
 
 			// primary access to portpkg
 			// This url returns the portpkg, not a human readable page
-		http://db.macports.org/portpkg/<portid>
+		http://db.macports.org/portpkg/<pkgid>
 		
-			// A portpkg defined by a query instead of a portid
-			// (will 301 redirect to http://db.macports.org/portpkg/<portid>)
+			// 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/portid/<portid>		(port instance by portid)
-		http://db.macports.org/tag/<tag>			(ports by tag)
+		http://db.macports.org/pkgid/<pkgid>		(portpkg by pkgid)
 		
 Issues for urls:
 
@@ -183,40 +172,35 @@
 Potential port(1) Actions:
 
 	port submit
-			==> category
 			==> portname
-			==> src package
-			==> info
+			==> portpkg
+			==> submission meta information, generically
 			<== status
-			<== porturl
+			<== pkgurl
 		-- Make a port submission
 			
-	port submissions
+	port query
 			==> portname
-			<== porturls (with additional meta? flags, tags, submitter, date, version, revision, status?)
-		-- Query port submissions
+			<== pkgurls (with additional meta? flags, tags, submitter, date, version, revision, status?)
+		-- Query portpkgs
 	
-	port flag_stable porturl
-		-- Promote a given port submission to stable status (requires authentication)
+	port flag_stable pkgurl
+		-- Promote a given portpkg to stable status (requires authentication)
 		
 	port submitreport
-			==> porturl
+			==> pkgurl
 			==> report data (??? tbd)
-		-- Submit a  report for a given port submission
+		-- Submit a report for a given portpkg
 	
 	port showreports
-			==> porturl
+			==> pkgurl
 			<== reports (??? tbd ...urls to the reports? or text?)
 		-- Query reports for a given port submission
 		
-	port fetch
-			==> porturl
-			<== srcpkg
-		-- Bring a given port into the local collection (or cache?) or ports	
+	port get (fetch conflicts with existing action!)
+			==> pkgurl
+			<== portpkg
+		-- Bring a given portpkg into the local collection (or cache?) or portpkgs	
 		
 		
 Document TODO:
-
-	- Rename "port instance" as "portpkg"
-	- Rename "portid" as "pkgid"
-	- Rename "porturl" as "pkgurl"

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20070405/1f686a52/attachment.html


More information about the macports-changes mailing list