%TOC%
++Name+
mystcl? catalytcl? kinetcl? attcl? systematcl? optcl? genetcl? grammatcl? elliptcl? gnostcl? identcl? linguistcl? practcl? phonetcl? cortcl? synaptcl? or maybe an acronym? tenet: tcl extention network

++Requirements+
+++Use cases+
development will proceed with the perspective of the repo being used in the following ways:
development will proceed with the perspective of the repository being used in the following ways:

  * programmers looking for specific functions
  programmers looking for new features which might be useful (browsing)
  programmers looking for a specific package
  programmers looking for package docs
  users looking for a dependency (this part needs to be very simple)

+++Metadata+
pkg metadata file must be both human and computer readable


|+Reqd|+Auto|+Data|
|  X  ||package name|
|  X  ||descr (short description)|
|||description|
|||categories/tags|
|  X  |  X  |package provides (might differ from human readable name)|
|  X  |  X  |filenames (does it have to be a single file?)|
|  X  |  X  |dependencies (needs to be in a format we can xref)|
|  X  |  X  |version|
|  X  ||platforms|
|  X  |  X  |type (binary/source/tcl/etc)|
|  X  ||installer (configure/make,script,binary installer, none, etc)|
||  X  |released date stamp|
||  X  |uploaded date stamp|
|||author|
|||relevant links?|
|||relevant links|
|||change log|
||  X  |commands provided|
|  X  |  X  |list of files installed by package|
||  X  |total size of installed files?|
|  X  |  X  |checksum|

+++Issues+
  * how to store metadata? all in db, or flat files?
  where do the docs go?

+++Repository Features+
  * where do the docs go?
  * must support binaries, source, pure tcl, starkits, .tm files.
  must handle multiple package types (source/binary/etc) and platforms for a single package. we could offer a small tcl installer that package maintainers could use, but the intention here is not to invent another packaging format or system.
  must handle nested categories (tags instead of categories?)
  can contain multiple versions of packages. only latest is displayed by default but full version history available
  package documentation
+++Required Repository Functionality+
  computer readable interface for package management apps. (REST?)
  browse by package names, categories, dates, platform
  searchable by commands, names, authors, description, manual
  rss feed of updates
  editing of metadata by maintainers after initial creation
  easy user contributions (include guidelines/howto)
  append comments to package pages
  rss feeds: category (or tag?), package, everything
  screenshots?
  RESTful api for package management apps
  browse by package names, tags, dates, platform, license
  searchable by commands, name, tag, author, description, docs

+++Client Features+
a client isnt quite within scope of the project but it might be good to release a basic usable demo client at the same time as the repository. there is also the possibility of an upload client. it could possibly provide some usability enhancements over a web interface.

  append comments to package pages (like php manual)
  rss feeds: tag, package, everything
  * command line or gui
  list installed packages and versions
+++Optional Repository Functionality+
Do not preclude these in the initial design but do not get overly ambitious
  search available packages
  * screenshots (per version or per package?)
  hosted version control
  trackers
  wiki per package
  update installed package(s)
+++Reference Client Features+
a client isnt quite within scope of the project but it might be good to release a basic usable reference client at the same time as the repository. there is also the possibility of an upload client which could possibly provide some usability enhancements over a web interface.

  install new package and dependencies
  remove package
  install in user sandbox and/or for the whole system (a bit beyond basic)
  ability for site administrators to customize the package list (a bit beyond basic)

++Questions+
  * how to resolve name collisions

+++Advanced Client Features+
  * install in user sandbox and/or for the whole system
  ability for site administrators to customize the package list

++Policies+
  * how to resolve name collisions? I think this will be up to the client
  * certain metadata bits are required (keep it minimal)
  versions cant be replaced, only incremented

  versions cant be replaced, only incremented. certain information is mutable without bumping the version, such as docs. data that is definitely *not* changable: name, license, released, provides
++Workflow+
++Site Organization+
The main sections should be as follows

  * browse
  ** name
     date
     tag
     license
  * search
  ** everything
     advanced
  * package home
    ** released, license, provides, requires, etc
       documentation
       older versions
    *** edit
  * package edit
  * account home
    ** user info
    ** projects
      *** new
  ** settings
  * help/faqs
    ** about
    ** contributing

+++Add new package+
  1 create a user account if needed
  upload files (does it have to be a single file?)
  app decodes files and captures as much metadata as possible
  user fills out web form adding or correcting metadata
  done
+++Update a package+
+++Remove a package+
2 cases:

  1 new upstream release, with a new version number etc.
  1 a packager may have fixed a mistake in an earlier upload and needs to replace it. So, same release version number built from the same source release, but it should still count as an "upgrade".  
+++Find a package+

Most Linux distributions append an auxilliary "release" or "build" number to the upstream version number to handle this case.  Example:

  1 upstream releases package foo version 3.4
  1 packager builds binary foo-3.4-1.tar.gz, signs it and uploads it to the repository
  1 packager finds mistake in packaging, needs to apply patch, or whatever
  1 packager fixes problem, builds binary foo-3.4-2.tar.gz and uploads that.

  1 use a client which uses the api (the client will present its own search, list, or other interface)
or
  1 hit the front page
  2 search, or browse by category/tag
+++Download and install a package+
  search, or browse by tag, etc
  1 find a package
  select a platform
  select a version
  select a package type (binary, source, pure tcl, etc) (optional)

++DB Schema+
  create table file (
  id integer primary key,
  filename varchar,
  size integer,
  checksum varchar,
  instance integer,
  foreign key (instance) references instance (id)
  );

  create table bundle (
  id integer primary key,
  name varchar,
  descr varchar,
  description text,
  provides varchar,
  -- key value pairs, eg home, docs, cvs, etc. should this be a table?
  links text,
  );

  create table instance (
  id integer primary key,
  bundle integer,
  version
  -- (binary/source/tcl/etc)
  type varchar,
  -- this only allows for one platform, but platform table could have entries like "unix", "windows", "all"
  platform integer,
  installer (configure/make,script,binary installer, none, etc)
  documentation text,
  uploaded_by integer,
  uploaded datetime,
  released date,
  modified datetime,
  modified_by integer,
  -- list of installed files?
  files text,
  -- sum of installed files
  size integer,
  commands varchar,
  author integer,
  license varchar,
  -- may create non "real" instances for purpose of depending on them
  real integer,
  foreign key (bundle) references bundle (id),
  foreign key (platform) references platform (id),
  foreign key (author, uploaded_by) references user (id,id)
  foreign key (author,uploaded_by,modified_by) references user (id,id,id)
  );

  create table dependencies (
  instance integer,
  package varchar,
  -- exact, greater than, conflicts, etc
  type varchar,
  -- tip 268 style version spec
  version varchar,
  foreign key (instance) references instance (id)
  );

  create table platform (
  id
  name
  identifier
  );

  create table user (
  id integer primary key,
  username varchar unique not null,
  password varchar,
  realname varchar,
  email varchar,
  registered datetime,
  login datetime,
  -- may create non "real" users for purpose of authors
  real integer
  );

  create table perms (
  bundle integer,
  user integer,
  -- perm string is single letter, or word? multiple words/letters per row or multiple rows?
  perm varchar,
  foreign key (bundle) references bundle (id),
  foreign key (user) references user (id)
  );

  create table tags (
  bundle integer,
  tag varchar,
  foreign key (bundle) references bundle (id)
  );

  create table comments (
  bundle integer,
  -- what to do about anonymous comments? maybe nonreal anonymous user entry
  user integer,
  comment text,
  posted datetime,
  foreign key (bundle) references bundle (id)
  );