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

source_changes at macosforge.org source_changes at macosforge.org
Wed Apr 4 10:04:37 PDT 2007 

Revision: 23558
          http://trac.macosforge.org/projects/macports/changeset/23558
Author:   jberry at macports.org
Date:     2007-04-04 10:04:36 -0700 (Wed, 04 Apr 2007)

Log Message:
-----------

More modifications to mpwa design doc:
 * Adopt 'port instance' as naming
 * Also use the term 'portpkg' to describe a bundled up port directory
 * Other clarifications

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

Modified: users/jberry/mpwa/doc/design.txt
===================================================================
--- users/jberry/mpwa/doc/design.txt	2007-04-04 16:31:31 UTC (rev 23557)
+++ users/jberry/mpwa/doc/design.txt	2007-04-04 17:04:36 UTC (rev 23558)
@@ -37,7 +37,7 @@
 	- The directory created for each submitted port 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 inforation, etc).
+	  submitter information, etc).
 	
 Additional:
 
@@ -45,49 +45,66 @@
 	  (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.)
+	  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, or perhaps the reputation of the submitter.
+	
 	- 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 submissions are final, unequivocal, and stable. Once a submission is
-	  made and assigned a a portid/porturl, it may not be edited. Any changes to the
+	- 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).
 	
 Nomenclature:
 
-	- "port": A unique id given to a submitted port.
-		Tried to stay away from port "version" or "revision".
+	- "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.
+	
+	- "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.
+
+	- "portid": The unique id assigned to the submission of port instance/portpkg at db.macports.org.
 		
-	- "porturl": a url that uniquely references a submitted port.
+	- "porturl": a url that uniquely references a portpkg.
 		This is probably formed in part from the portid.
+		
+Storage layout within the macports subversion repository:
 
-Storage layout within the macports repository:
-
-	/port/submissions/catname/portname
-		/common/<unpacked directory tree> (revisioned/shared between submissions of the port)
-		/<portid>
-			/port.tgz (the submitted tarred-up port directory tree)
-			/unpacked/<directory tree>
-			/meta/
-				/submission_info
-				/comments (user comments?)
-				/reports (build logs?)
-				/status (build status?)
-			/binaries (potential future expansion)
+	/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
+					/portpkg.tgz (the bundled/compressed portpkg)
+					/unpacked/<directory tree> (the unbundled/uncompressed portpkg)
+					/meta
+						/submission_info
+						/comments (user comments?)
+						/reports (build logs?)
+						/status (build status?)
+					/binaries (potential future expansion)
 			
 Issues:
 
 	- 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
+	  in the database vs in the instance 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.
@@ -100,8 +117,8 @@
 	  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)
+		- n submissions/instances of each port (even including potentially multiple 
+		  instances per epoch-version-revision)
 		- tags
 		- flags
 		
@@ -110,7 +127,7 @@
 		
 	- 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.
+	  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,
@@ -119,11 +136,11 @@
 	  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 stable port version
-	  lose that designation? Or is it possible to determine that a port submission was previously
+	  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
 	  stable? And if so, that brings up the need to be able to determine the "latest stable"
-	  submission 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 submissions
+	  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
 	  of a port as needed?
 	
 	- Though we provide a network-accessible location and unique urls for ports, we should not
@@ -137,19 +154,19 @@
 	
 Potential public urls for ports:
 
-			// primary access to port src packages
-			// This url returns the source package, not a human readable page
-		http://db.macports.org/srcpkg/<portid>
+			// primary access to portpkg
+			// This url returns the portpkg, not a human readable page
+		http://db.macports.org/portpkg/<portid>
 		
-			// A srcpkg defined by a query instead of a portid
-			// (will 301 redirect to http://db.macports.org/srcpkg/<portid>)
-		http://db.macports.org/srcpkg/latest/<portname>
-		http://db.macports.org/srcpkg/stable/<portname>
+			// A portpkg defined by a query instead of a portid
+			// (will 301 redirect to http://db.macports.org/portpkg/<portid>)
+		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/port/<portname>		(port by name)
-		http://db.macports.org/portid/<portid>		(port submissions by portid)
+		http://db.macports.org/portid/<portid>		(port instance by portid)
 		http://db.macports.org/tag/<tag>			(ports by tag)
 		
 Issues for urls:
@@ -157,7 +174,7 @@
 	- 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 submission that is desired, and yet maintain a one-to-one mapping between
+	  particular instance that is desired, and yet maintain a one-to-one mapping between
 	  url and port.
 		
 ======

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

More information about the macports-changes mailing list