PrototypeA
From Metagovernment - Government of, by, and for all the people
This is a basic outline of the initial implementation of Metascore.
The software runs on a central server and is delivered through a browser. The software is written in Python and uses the Django web framework. A relational database is used as the datastore for users, messages, tags scores and various other design specific models, described later in this document.
Resolutions will be stored in a mercurial repository and editable through a wiki like interface, as well as locally through the standard mercurial software. The fronted uses XHTML, CSS and the Dojo toolkit.
Contents |
Participation
This document is a work in progress, please give feedback and edit freely. Some of the ideas here have been discussed in other places and the reasons for certain decisions may not be given. If the reason for a specific decision is unclear, please ask, add references, or add the reasons to the document.
The progress of the implementation is documented in the PrototypeA_Roadmap.
If you are not familiar with mercurial, you may want to check out the introductory sections at: http://hgbook.red-bean.com/hgbook.html
The repository associated with this prototype is managed in Mercurial and is available on bitbucket.org.
If you have mercurial installed, you can use the command:
A guide for setting up django can be found here: http://www.djangobook.com/en/1.0/chapter02/
Pair Programming
If you would like to discuss or get to know the code, we have started pair programming and you are welcome to participate. This is more efficient and fun for coding, but it should be noted, that any important decisions and discussions, should be documented in the most relevant forum (the wiki, the mailinglists or in the code itself).
Please note your skypeid below if you would like to participate. Alternatively you can write to the dev mailing list and we can work something out.
- mbarkhau (English/German)
- fbarkhau (English/German)
Resources
A resource can be a message, user, resolution, changeset etc. see below for a detailed description of each.
Identifiers
Common to all resources, is that they have a unique identifier with a common prefix for that resource. A message for example can be uniquely identified by the prefix "msg"(Note that the prefixes can have arbitrary length and may vary between translations.) and an id.
A dash is used as a separator between prefix and id ("msg-123456789" or "msg-This_Is_An_EX_Parrot!". For convenience, the message may also be identified by the prefix and it's title, so long as it is unique. This is the preferred display method in the user interface, though internally only the unique identifiers are used.
Identifiers allow the various resources be referenced by each other, in the form of a tag. We can tag a message, with the identifier of a resolution and thereby establish connections between various resources.
Messages
Messages can be written by any user and require no registration. They use the prefix "msg". A reply is implemented, by automatically referencing the parent message. A message, so that a threaded view may of a conversation may not be appropriate.<ref>This may be confusing, needs discussion</ref>
There should be writing guidelines, that encourage an organized and civilized debate. Messages may be saved (drafted) before they are published, since users may take their time while composing.
User
A user can write messages, give scores to resources and write or edit resolutions. Each user has his own branch in the repository, which can also be accessed with the standard mercurial tools. The user may however only push to his own branch.
Registration is open to anybody, but over time the scoring system will allow users to increase their rank, so not all users are equal. Apart from displaying the recognition a user has gathered in the community the rank may be used to loosen certain restrictions on interacting with Metascore. Restrictions should only be imposed to prevent spam and abuse<ref>clear definition of spam needed</ref>. Identifiers use the prefix "user".
Group
A group can do everything a user can, with the difference, that the group may specify, that messages must be signed off by specific members or at a certain percentage of the group, before they are published. Ranks of the members may be aggregated by the scoring algorithms. A user may be a member of any number of groups. There may be a manifest associated with a group in which it may declare its purpose, principles etc.
Resolution
A resolution is stored in the repository as a single file with the id being its filename. Resolutions use the prefix "res". Resolutions are edited in the branches of users. The "main" branch contains only approved resolutions, which have been merged from the users branches.
Merging to the main branch is handled by Metascore, while the users have complete control over their own branches. Resolutions should conform to a few guidelines, so they can be parsed by metascore. The should have a short name, which is used for their reference tag and contain a short introductory/summary paragraph, which may be displayed by the system, when the complete resolution is not appropriate.
Vote
For now, a vote will be nothing more than a non binding poll. It may be used, to gauge the mood in the community and can be issued by any user. If they are ever used to make a decision, they should come with a Big Fat Disclaimer.
Interface
The following describes the layout and interface for displaying and interacting with the various resources.
A graphic designer would be nice, until then the design will be plain and functional. Some interactive elements will be enabled with fancy ajax and whatnot, for this we use the dojo toolkit.
Score display
Should we display scores to the user. On the one hand, it might bias them, on the other hand it would offer them greater transparency of how the system is working. Certainly scores should be displayed, after the user has given a resource a score.
Messages
There are various pages to view the messages posted on metascore. The first view is the overview of current relevant<ref>as determined by the scoring algorithm</ref> messages. Only title, author and submission date are shown for each message. Note that each message is considered by itself, that is a reply to another message will also show up here. Navigation among a thread can be done from any message in that thread. This should help give each message a fair amount of visibility, so that it can be scored.
Display of individual messages should be fairly obvious. Under each message are the tags that have been applied to it and (if logged in) a input for adding new tags. The message is parsed for potential tags.
Resolutions
Though users can use their branches, as with any other mercurial repository, we will also offer a wiki like interface for editing resolutions (or any other content in the repository). When displaying a file from the repository, any versions of that file on other branches, will be visible and the differences can be displayed.
Scoreing
The specific interpretation of scores is yet to be determined, but the underlying storage mechanism will be the same, across the various algorithms, that use them.
A user may give a score to any of the resources described above. Scores are internally stored as a floating point number with a value between -1 and +1.
TODO: Algorithms
Types
There are various types of scores, which give the user better control over giving their opinion on a resource. The most basic score will be used to express agreement. A more complex score is the synthesis score, which indicates that a resolution synthesizes its referenced resolutions.
Tagging
The primary means of organizing the resources in metascore is through tags. While scores provide the mechanism to determine the value of a resource, tags provide information on what attributes apply to a resource. Tags are the primary means, for navigating content in Metascore.
Reference Tags
As mentioned earlier, each resource has a unique identifier, which can be applied to another, in the form of a tag. If a message reffers to a resolution, the reference tag such as "res-123456"
Syntax
A tag may contain any unicode character but the following:
- " " space, which is used for separation when entering multiple new tags
- "-" dash, which is used as a separator between prefixes and ids of resources.
- "*" plus, which is used to search for the intersection of tags.
- "+" plus, which is used to search for the union of tags.
- "(" and ")" to be used to create complex requests like (A union B) intesection (C union D).
- "\" to be used as set minus (A\B are the elements which are in A but not in B)
Weight
Each time a tag is applied to a resource, a weight is associated with that tag. More precisely a weight is associated with the /application/ of that tag to a resource by a user. Multiple users may apply the same tag to the same resource but with different weights. The weight of a tag is determined by the order in which the user specified the group of tags for a resource. The sum of weights of this group of tags is 1. The distribution of the weights follow a power law with steepness 1.1.
Given n tags their relative weight will be:
y=f(x)=a*x^(-1.1)
if we have n values, the x will be = 1, 2, ..., n-1, n
with a = 1/ ( 1^(-1.1)+ 2^(-1.1)+ 3^(-1.1)+... ...+(n-1)^(-1.1)+n^(-1.1) )
When we then substitute the a in the f(x) and we calculate the y for each value of x equal (1,2,3,...,n-1,n) we should get a series of points that approximate a power law such that the f(1)+f(2)+f(3)+... ...+f(n-1)+f(n) = 1
Repository
The server has a repository containing all resolutions. In addition, it may contain the currently running metascore software to conform with the AfferoGPL.
Editing of legislation is done in the repository. Anybody can check out from the central repository, and commit to a branch registered to their username. By default, every user has their own branch from the "main" branch of the community. They can push their changes to their own branch, as well as the branch of any group they belong to.
When a user or group wants a resolution to be merged into the "main" branch, it is published for discussion in the entire community. If the community accepts, either by consensus or a majority vote (threshold to be determined), it is merged to the main branch and thereby becomes part of the accepted law of the community.
More generally speaking, this procedure applies to any any changesets, including amendments or deletions of resolutions which are to be merged into the main repository.
Self Hosting
Once repository interaction is possible, we will start using metascore to develop itself: hosting the code of metascore in the repository it operates upon. A stable branch will contain the code that runs on the server, while development continues on user branches. Changesets approved by the community will be merged into the stable branch.
Future Development
The aforementioned functions are the basic functions we intend to implement for version 1.0. The following are features, which aren't essential to the project for now, but may greatly increase the usability of the website. Feel free to add feature requests here.
- All pages should be accessible and usable via a mobile web browser.
- While the page may make use of javascript, it should not be required.
- RSS feeds for tags (lists resources to which a tag is applied)
- RSS feeds to all events in the life cycle of a resolution
- messages to discussions in which the user participates will be sent regardless of subscription
- Participation via e-mail
Development archives
- List server archives
- Chat logs: PrototypeA/ChatLog
