Requirements for PoshCode Repository
First Requirements Meeting Notes
- items with - are things we NEED to have
- items with + are things that would be nice
- items with ? are things we need to DECIDE about
I think we can store a lot of the data we want to store as special key:value "tags" so we can render them to the scripts in "data language" or comments (or data language in comments). I think we should consider "Machine Tags"1
as a way to make this extensible by third party repositories.
- Easy in, Easy out, Low Barriers (no mandatory registration, no login to download).
- Multi-file artifacts (script modules [|#ScriptModules]).
- Browsing and Searching in the WebUI.
This is the list of things we want to know about a script (ie: data we need to store
- - The script itself. Scripts, snippets, examples, modules, compiled modules([|#ScriptModules])
- - The version 2 ... ScriptFileID and ModuleID
- - The date of submission (for ordering)
- - The author (OpenID url? email address?)
- ? Function and/or Cmdlet Name(s)
- - A description
- ? Usage (i.e. the -? help...)
- ? Example (do we really need to ask for these things separately? Shouldn't they put it into comments or a -? argument handler?)
- + Dependencies (PowerShell version, .Net Version, module or scripts)3
- + User Tagging (including non-authors?)
- - Nouns!
- ? License? (offer a selection: CC, Ms, GPL, etc., and prepend a "short form" license comment).
- ? Feedback (Comments, Ratings)
Third Party Modules
? Download Url (for v2?)
We would like to persist some of this data for people who download the artifacts ... either by embedding it in comments, or by including a psd1 manifest.
Web Service API
The goal is to define a standard web service api that anyone can implement (this means not making the API technology independent -- so you can implement it and call it from Asp/Wcf/Php/PowerShell/C#/Whatever).
The API should support:
- - searching and browsing (by author, verb, noun, tag, fulltext)
- - summaries (we need a "ScriptInfo" object: description, author, date, id/hash, version...)
- - downloading (by id)
- - authentication (note that OpenID requires Web UI)
- - uploading (with all the data, somehow -- should validate mandatory data)
- ? commenting
- ? tagging
At a minimum we need a WebUI
and Cmdlets for accessing the API. Ideally they would be implemented strictly against the API so either the WebUI or the cmdlets could access any implementation of it. Perhaps we should not open source the WebUI (or should make it strictly GPL?). Additionally, there are some other ideas...
Stats (for convincing people to support "our" repository)
- Number of Authors
- Number of Postings (rate per day, total count, unique scripts not counting versions)
- Downloads, (Script) Page Views?
- RSS subscribers?
Claims Based Trust
Could there be a way to verify claims about scripts? using the tokenizer? using trusted authors? Eg: we could create a claims system where the uploader claims:
A. Doesn't use .Net classes
B. Doesn't modify files
C. Doesn't modify registry settings
... or whatever. Some claims could be automatically validated, and some would need to be validated by users/authors, and/or ...
Should we sign the data we embed in the scripts? That is, sign our portion of the data for our own sake -- so we can track history and authorship (based on logins) with confidence.
- Machine Tags: (see Wikipedia and the original post on flickr) might let us differentiate tags that are about required libraries, etc ... but would also let other repositories extend the storage and still store the data in a way we could use. E.g.: Use our web domain for as the namespace so if there are many compatible sites, poshcode.org could have tags like "WMI" and "VMWare" and "WPF" ... but also like "requires:VIToolkit" or "requires:2.0" or "requires:PSCX" ... and could store them in the script as poshcode.org=tag:WMI, poshcode.org=requires:PSCX etc.
- Versioning: J. Snover had a good idea about versioning, to hash the script body and use the hash as the id of the script ... The idea is that you would then insert that as a comment into script (header? footer?), and when someone submits a script that already has an id line in it, you could assume the new script is a new version of that script, and you could keep them all there, as a history of versions for tracking scripts. We could store that as an indexed field in the db and use it in urls too: It would be practically unique, but portable across sites for unmodified scripts!
- Dependencies: The module or script dependencies should be URLs or the hashes from 2, and could probably be deduced from "#requires http://URL" in the comments.
- Script modules: (and modules in general) require some system for storing multiple files as part of a single "artifact", and for downloading them all at once. We also need to track versioning of the "whole" package, and have an API/interface for uploading them, viewing them, and downloading them (I'm not sure if we really need to support downloading single files from a multi-file artifacts, but obviously in a WebUI you'd want to be able to show the source if it was a script module, right?)
- Compiled modules: Do we support compiled modules in any way? If so, how? We do NOT compile, but do we provide full source packages? They could include a MSBuild file (like a visual studio project file) and the cmdlet could hypothetically compile it. How about modules like PSCX (which is open source, but has source control elsewhere), could we (safely) provide a ScriptInfo with download URL pointing to the project's hosting? What about commercial projects? We can put off deciding this stuff until after V1 is out ;-)