Skip to content

Specification

Jump to bottom Edit New page
JamesHarrison edited this page Aug 27, 2010 · 2 revisions

Project Specification

CSM and CCP combined issue tracker design specification, early draft

THIS IS NOT BUGZILLA. It is too completely different from the models any existing issue tracking software provides to be done with that nicely. So this is a ground-up approach. Because we can. And cakes baked from scratch are best. As are cookies. If you are TRULY agile, that is.

Overall Project Goal: Create a shared environment for CCP, the CSM, and the playerbase to intelligently submit, update, organize, track, and prioritize Proposals related to the development of EVE-Online. The CSM can then moderate this service, creating and managing Proposals and Proposal Sets. These Proposals would help to focus what the CSM brings to CCP during their tenure, and provide a way of tracking and accounting for actions undertaken by CCP in support of the CSM and proposed ideas.

CODE TRIVIA FOR CODE MONKEYS

External References

List of Topics in this Document

  • Terms and Definitions
  • General Workflow for Proposal Processing
  • Validation of Users
  • Tracking of User Demographics
  • Submission of Issues
  • Collation of Similar/Related Proposals into Sets
  • Tracking of Issues
  • Service API Functionality
  • Moderation of the Service
  • Proposed Categories
  • Rough Model Sketch
  • User Stories
  • Ideas to Consider in the Future

Terms and Definitions

COLLABORATORS: Please add new entries in ALPHABETICAL ORDER and using the same format as existing entries. IF YOU CHANGE THE DEFINITION FOR A TERM that changes its meaning, you MUST go through the entire document and make sure that term is correctly used in accordance with your definition. OR PERISH.

  • Account. An account with CCP for playing EVE Online. One or more Accounts may be attached to a single User, for the purposes of changing the User’s vote weight by virtue of considering the extra accounts, as is currently done for users posting with mains and alts in the Assembly Hall.
  • Amendment. A suggestion made by a user for the purpose of changing an open proposal.
  • Issue. A Proposal that has been raised in a CSM working meeting and voted either Pass or Fail by the CSM. This is logically (in the DB) a Proposal, but refers to Proposals that have been voted on by the CSM.
  • Proposal. A suggestion made by a user, either on the Assembly Hall or in Nebula, for a change that they wish the CSM to champion to CCP. Proposals are sometimes referred to as “Issues” but for sake of consistency, please use the term “Proposal”.
  • Proposal Set. One or more proposals on the same topic, collated by a CSM member, for streamlining the raising of multiple similar proposals to the CSM. These sets are for organizational purposes only, but are publicly visible. Addition to a proposal set does not change the status of a proposal, nor does it change the mechanics of CSM members raising proposals for CSM meetings.
  • State. A State is a status in which a Proposal can be which identifies the phase of the workflow/process in which that Proposal currently lies.
  • State Change. An indicator of a change between one state and another which can be used to track the progress of a Proposal through the process.
  • User. A single user of Nebula. A user must have one or more Eve Online accounts attached to their account to allow them to participate in Nebula.

General Workflow for Proposal Processing

  1. Players write and submit proposals in Nebula.
  2. CSMs select individual proposals or collated Proposal Sets for raising at meetings.
  3. CSM votes on raised proposals.
  4. CSM submits passed proposals to CCP.
  5. CCP response with Yes, No, Maybe.
  6. Proposals awarded Yes (and sometimes Maybe) go into Backlog.
  7. ???
  8. Profit!

Validation of Users

Goal: Allow active account-owners in EVE online to use the service with minimum hassle, and prevent abuse of the system via anonymous spamming of votes or other actions.

  • Limited API required, multiple API keys to proposal tracker association for ease of use of multi-account users.
  • The following ‘suspicious’ account categories will require manual validation.
  • Accounts on which the highest SP character is under 3 million SP.
  • Users which have registered on the same IP address as another user.
  • Accounts added to a User account with more than 2 other Accounts already added.
  • Manual validation will be accomplished by having the character send 0.10 (or more) ISK to a specific corporation in-game

Reasoning: API verification prevents character recycling on individual accounts. For accounts which failed the automatic (see above) validation, manual validation of sending 0.10 ISK to a predesignated location is used to prevent abuse of trials and mass signup/account adding by people harvesting API keys. There is no precaution against using multiple or reactivated accounts, since these are accepted in other places with precedent (CSM, etc). Although the intent is to have Nebula fully transparent and open to the public, usage requires verification. Lapsed accounts and invalid/exipred API keys will not affect previous votes. If an API key cannot be validated it must be updated with the new key or removed before a User may vote again or perform other actions.

Tracking of User Demographics

Goal: To allow the CSM and all players to see statistical information on the demographics of the players registered to use Nebula. None of the data shall be personally identifiable. Additionally, topics with more than X users voting on it (different than total votes) shows demographis for those who voted on that issue (total, upvote only, downvote only).

  • Collection – mandatory survey on registration, should be made very clear they are user-wide and not just one account
  • Metrics:
  • How to determine this?
  • How to allow modification/updating of collected data?
  • Versioning of results
  • Proposed starting set of metrics
  • Main location – highsec, lowsec, nullsec (NPC), nullsec (alliance), wormholes
  • Secondary location – highsec, lowsec… etc
  • Wealth (including assets) – <10mISK, <100mISK, <250mISK, <500mISK, <1000mISK, <5000mISK, <10000mISK, >10000mISK (We might want different ranges, like < 100m, < 1b, < 10b, < 100b, 100b+)
  • Corporation type – Market, Mining, PI, Pirate, Nullsec Alliance, Other Industrial, Other PvP (These so need better labels), Nublet corp,
  • Main activity – Industry/R&D, PvE, PvP, PI, Market Warfare, Missions, Other (Some of us do none of these and make our own game)
  • Secondary activity – same list
  • First played EVE – beta,
  • Age – <list of age brackets, 10 year increments>
  • Corporation size – Small (<25), medium (<100), large (100+)
  • Primary in-game money source – Mining, Industry, PI, Missions, Research, PvP, PvE, business, etc

Submission of Issues

Goal: Allow users to submit issues but try to prevent duplicate issues and issue spam. Remember, Assembly Hall = discussion stage, once it consolidates, then it comes here.

QUESTION (from Mynxee): Is it possible to pull OPs from proposals submitted to AH, including subject, body, and parsed list of supports from respondents? Rather than having users submit proposals initially in this tool? Or is that part of the plan anyway? Because this tool will be optional so how do we ensure a “complete” data set if some don’t bother to use it and stick with the AH method? And how do we pull in all the existing historical data—or at least that for some time period past? We might be able to extract from the wiki for past issues (those that have been incorporated there) Plausible but perhaps not desirable.

IDEA (from Johnathan Walker): Couple of thoughts on this. Not sure where technology is at these days, but it could be possible to scrape the information straight from the web page. While I’m thinking about that, there is eve-search (Chribba?); might be able to get a data dump from there on some form of consitent basis.
I would strongly caution this. Even if the data set is good, the format is different – we’re not aiming to be a forum, so imported forum replies wouldn’t fit the site very well. I would strongly encourage resubmission – if people care, they will be happy to do so.

Proposal States

A proposal will always be in one of the following states:

Virgin -—
  • New. A Proposal that is less than 7 days old. Used to keep Proposals from being open to all normal actions until they are at least in view for a week.
  • Open. Issue that is at least 7 days old but not yet raised or voted on by CSM
  • Locked. Proposals that have been “locked” by admins. A way to prevent further attention to joke or non-serious proposals; in this state, can no longer be voted on and possibly does not show up on various lists except for a Locked list. Do we need to provide a reason? Needs more discussion! (JW): Personally speaking and since transparency/excellency is a recurring theme for Nebula and beyond, I would say yes. A simple one liner should suffice, yes? (also applies to Withdrawn status).
  • Withdrawn. Proposals that have been taken out of consideration by the proposer. In this state, can no longer be voted on and possibly does not show up on various lists except for a Withdrawn list. Should there be a way to enter the reason for the withdrawal? Needs more discussion!
  • Expired – No votes (up or down) and no comments in the last 30 days, issue is locked. Can be re-opened by CSM members. Suggest “Dormant” for this state (Trebor)
Been Kissed -—
  • Raised: Selected by a CSM member for voting upon at a future meeting. It is not possible to approve amendments past this point except as a CSM member.
  • Failed: Voted on and failed by CSM – No further voting is permitted at this point – or do we go back to the open state to allow for issues to be further amended?
  • Passed. Voted on and passed by CSM. No amendments may be made, voting is still permitted. Note this is not the same thing as Submitted, because a fair amount of time may pass between a Proposal being Passed and it getting Submitted to CCP, since this is done in batches.
  • Submitted: Submitted to CCP for consideration – No amendments may be made, voting is still permitted
Naked -—
  • Denied. CCP said “No” but may also mean denied for fail / so much stupidity it is just funny. Need more discussion here, should voting still be permitted?
  • Backlogged. CCP said “Yes” and it’s been placed in the backlog. – Voting no longer permitted.
  • Maybe. CCP said “Maybe” and it probably needs technical/CSM discussion; need a better State name than “Maybe” though. Should voting still be permitted?
  • Duplicate. This issue already existed.
Orgasm Achieved -—
  • Implemented. Proposal has been implemented in-game. In this state, can no longer be voted on.

Question (from Mynxee): Who is responsible for updating the state of a proposal? In my view, will fall to CSMs to do this, and thus should not be left up to users. Also, yes, I am guilty of those randy organizational dividers LOL.
CSM members, all of this should contain visible tracking anyhow of who actually works for his money, so to speak :P (from Mynxee cuz Virt stole my red color today: Yes, agreed, who did the moderation should be visible because what if you want to question them about why?).

Notes:

  1. Open Issue Limit
    • Each user is able to have X “new” issues per account at most.
    • User can delete or edit their own issues – only if the issue hasn’t already been voted on or ammended (at least X votes or something, not just 1 vote)
    • Up amount that can be submitted based on positive feedback – X issues extra given on an issue being used in a proposal, X issues given on n% of vote (not sure about that second bit, can be gamed)
    • Sitting CSM have no issue limit
  2. Throttle Proposals
    • Selene – 3 open per account max, X upvotes or an issue age of 14 days makes an issue not count towards the total. Allow limits to be upped from 3 for users via petition to CSM.
    • Mynxee – Submit no more than 1 per day or total of 6 per month; count total for issues expires on issues older than 3 months; given what I see in the AH, that wouldn’t cripple anyone and would prevent spamming.
    • Omber Zombie (oz) – issue count gets reset (-1) for any issue that is defined as passed/failed/submitted/backlog/rejected
  3. Duplicates and Related Issues
    • Automatically tracking duplicates is near impossible, the voting system (the users) need to make sure a duplicated issue gets voted down fast (i.e. disappears from the front-side/page). Feature a page/report that shows duplicates perhaps also.
    • When submitting, show related issues via search on keywords and/or tags.
  4. Automatic Issue Raising
    • Selene response: I believe this was 5% of the number of users who participated in the most recent CSM election. The rationalization was that this leaves an option where an issue is forced to be discussed, even though CSM would realistically address it much sooner, it does give some motivation to the users to bring more attention to their issues. Could be good, could be useless, who knows! =D
    • CSM voting figures will have to be manually set by the CSM post-election. Sugggest <1000 votes result in disabling of 5% positive auto-proposal – otherwise potential for too many issues being made automatically open/proposed/proposed.
    • The 5% rule was included in the original CSM white paper. Basically, it said that if 5% of subscribed accounts supported an issue, it was automatically raised by CSM without a vote. That rule was IIRC changed in CSM2 to 25% of the vote count in the most recent CSM election. Citation neededYeah, looking. :-)Damn old CSM shit, it’s hard to find this stuff. Citation not found.
      • RE: 5% citation, CSM1 – JW:
        • “0010 5% Voting Issues: Pétur (CCP) explained that the current 5% amount of players to bring an issue to the CSM was to ensure that not a single Alliance could force their issues through, but that 5,000 votes would be a more practical number at the moment. CCP wants to keep this democratic mechanism in place, but understands that either the percentage will be too high so that it would never be obtained or too low so that a single Alliance can force all its issues through.
        • The CSM conferred on its own and changed the required percentage to 25% of the amount of people that voted in the election."
          • Source: http://www.eveonline.com/ingameboard.asp?a=topic&threadID=819225&page=1#10
        • 0010 5% voting issues (continued)
        • After discussing and evaluating several options, the CSM voted to change the amount of required votes to bring a proposal to the CSM from 5% of the playerbase to 25% of the amount of people that voted in the election, effectively lowering it to 2.75%.
          • Source: http://www.eveonline.com/ingameboard.asp?a=topic&threadID=819225&page=1#28
  5. Merging of Issues (We don’t want to do this. No no no no no.)
    • Regarding merged issues, some considerations: Let CSMs tag duplicates for proposed merger; those are then listed in a “merger approval queue” on a CSM Admin page; comments and vote yes/no on merger would be a nice ability to have; require some minimum # of votes to enable merger. Merged issues should preserve all text from all issues. Editing out redundancies can be done later. We also discussed not merging, but either always rejecting duplicates or allowing an option to make the duplicate show up as a discussion or amendment to an existing issue. (This avoids the messy merge scenario completely.)
    • - RE: Merging… maybe attach duplicate to an existing issue as a child/attachment with text?
    • RE Merging: My personal opinion is OH DEAR GOD NO WHY ARE WE EVEN THINKING ABOUT THIS. Merging doesn’t apply cleanly to CSM issues; these are personal, well thought out (we hope) issues that people will take offense to having merged into other people’s things (losing them credit). Deduping by referencing and closing is clean, simple and avoids all sorts of horrid problems attached to merging, and gives us a framework for ‘related issues’ etc should we choose to go down that route. Closed issues can be submitted by the user to the living issue as an amendment if they wish.++Merging should be entirely the perogative of issue owners. If two owners wish to merge their issues, they can feel free. But no mergers from above. (This is a very low-priority feature, can be excluded if it’s difficult, IMO – “mergers” can just as easily take the form of editing the OP to say “OtherGuy does this better, vote for his at .”) This is what amendments are for. Amendments don’t clean up old duplicated issues – if someone says “Oh shit, mine’s a duplicate”, then mergers are handy. That said, we don’t need a “merger” mechanic for people to do that, so it’s no big deal. A CSM that wants to raise an issue which has dupes can always talk to the proposers and negotiate an outcome.Or they can just pass whichever version they like best ;)

Reasoning: Limited number of issues with additional issues granted on successful issue proposals encourages good issues and discourages unlikely to succeed issues, while preventing large-scale spam. This encourages quality over quantity without compromising the ability of good contributors to contribute.

Collation of Similar/Related Proposals into Sets

Goal: Allow the CSM to create sets of Issues that are merged together to address a complete issue. Example: low-sec revitalization.

  • Only allow CSM members to do this. This can probably be used with some kind of CSM platform/election service, but we may want to avoid politics as well.

Reasoning: Players tend not to follow all issues, whereas CSM mebers tend to look them all over and will see emerging patterns or a way to group similar issues into a single proposal.

Rating of Issues

Goal: Useful feedback. Prevent issue spam.

  • Issues can be voted on by users (votes being associated publicly with a character)
  • Votes may be positive or negative
  • On issues, one account, one vote. Users configure their voting character when adding their API key. Voting adds all characters as n seperate votes transparently, adding all characters

Reasoning: Both support and anti-support need to be represented since changes can have negative influences on the playerbase. We also want to make life simple for multiple account holders, if they can deal with trusting the service to keep linked account information private.

Each user has a number of Eve accounts associated with it, by API checks. The number of accounts attached to the user is the vote weight that user has. A user with three Eve accounts gets three votes in Nebula. Each user may change their vote on any issue/amendment at any time, to support/oppose/abstain. Changing to abstain is the same as having never voted on the issue at all.

When a user gains an account – say, by creating a new alt in Eve – the user will be given a button to update their vote total on all previously voted on, still open issues and amendments. That button will go back and retroactively add one vote to each of those issues(e.g., if the user opposed an issue with two votes, and they gain a third Eve account, they will now oppose it with three votes, if they wish to go back and update)

When a user loses an account – say, by cancelling an alt in Eve – all previous vote weight derived from that account is locked. The user can no longer change it, but it continues to be counted in the vote totals. The API key will need to be re-checked daily(or not daily, maybe monthly, while I may want to give my API to vote on stuff, I sure as hell will change my key right after. Not tracking of my wealth and stuff – This is not viable, making accounts effectively untrackable in terms of activity from day to day is potentially open to abuse; storing data like wealth will not be done, just character→account mapping and some amount of demographic data which will be made clear to users before signup) to ensure continued activity of the account. If an account is lost, the user will be prompted on the next login for new API data(to cover the case where the API key is re-created – perhaps only give this option if the API error thrown is invalid credentials, change the option to “Re-check, my account is re-subscribed” for “deined by account status” errors). If the user refuses, the user’s vote weight goes down accordingly.

If an API check fails more than 3 times (ie 3 checks over 3 days), the votes associated with that account are removed. Upon logging back in, the user is prompted to re-add the account, at which point votes are restored, or votes remain removed if keys are not updated.

If all accounts associated with the user are lost, the user can no longer create issues or amendments. Option – do we allow them to continue to administer their previously-created issues, or do we hand off admin rights on them to CSM/let those rights go dormant?
Ownership of issues should not be altered; CSM can still approve amendments to existing issues, and handle administration.

Tracking of Issue Status

Goal: Allow users to be kept informed of changes made to issues they have voted upon or decided to follow/track, while not actually killing the server sending out emails.

  • Allow CSM and devs to change the state of an issue or proposal
  • Link to AH proposals for completeness and visibility. Encourage reverse linking.
  • Allow users to ‘follow’ an issue and get emailed when updates are made (amendments or state changes)
  • Post changes to issues on Twitter – only major state changes?

Reasoning: We want to both give all issues an informative state which explains where they are in the CSM/CCP process, and to make useful states that users can search on.

Service API Functionality

Goal: Provide an API to issues and data about issues. Focus on letting others see updates on things they care about (tag based, etc) and on other websites showing information about issues and proposals.

  • Include common queries, and provide title, proposer, lastedit, submittion time, text, status, taglist, …..
  • Investigate exporting data to HanSoft for CCP usage
  • Programmer API to be implemented in XML and JSON/JSONP output formats, GET parameters for all variables to keep it simple
  • Provide simple HTML/JS widgets for people to embed issues/top 5 issues/tagged issues on their blogs
  • Facebook widgets (They’re pretty simple to make) to embed issues/top 5 issues/tagged issues

Reasoning: APIs can be good, if kept simple and clear. We want people to see this service everywhere, and use it as much as possible, since that is the goal — get player involvement and focus it in a useful way.

Moderation of the Service

Goal: Allow the service to be kept responsive and transparent while preventing spam and crap from filling up the works, and to keep all moderation actions publicly (to those it affects) transparent/auditable

  • CSM members would have moderation abilities
  • ex-CSM in good standing would to some extent as well
  • A set of eve (not CCP) developers would also have some kind of …. oversight? Prevent dev abuse? (Transparency is important)
  • CCP dev comments or ammendments based on technical factors could be really helpful
  • CCP Oversight? – Discussion.
    • Dev oversight is needed, as hammer from god element, case of trust + exchange + NDA enforcement (unlikely, but good for them to have option to).
    • Selene: CCP can’t do much if the players and CSM find this useful. Also this is aimed towards player/CSM communication, not CCP involvement (though direct technical amendments from them could be very helpful). CCP are mainly involved via engagement with the CSM over issues raised here. Also the NDA never comes up in this context, since all issues are player raised.
    • Trebor: public CCP partipation is a win. They should have some limited, non-destructive powers, such as temp-hiding a issue or posting pending CSM/admin review. The fact that they have done this should be public.

Reasoning: Moderation would primarily fall on CSM and ex-CSM members since they are the ones informed (lol) of changes made to issues and are also aware of when issues are proposed. This also makes sense since they are the actual elected officials and this site serves as a way of organizing information communicated to the CSM by the EVE-Online playerbase.

Proposed Categories

  • Feature Request
  • Design Defect
  • Balancing
  • Art
  • Sound
  • Meta (Forums, EVE-Gate, Policy)
  • Lingering Bug
  • API (Should be a tag, not a category – categories are about what the issue is, not what it’s about) There are a few API issues that have come up in the past (adding extra data to the blueprint API for example), so it should either be in meta or have it’s own category.

Rough Model Sketch

(Excessive capitalization is intentional – this section refers to ActiveRecord language)

  • Issues belong to a State and Character and User and have many Amendments and StateChanges
  • Amendments belong to an Issue and a Character
  • States have many Issues through join model
  • References belong to two issues, from and to, and have many types (STI) – DuplicateReference, RelatedReference
  • StateChanges belong to a state and an Issue or Proposal (hooray polymorphism!), are time stamped and have an optional link to a Proposal
  • Proposals have many issues and Amendments through join models (again polymorphism Issue/Proposal). Associated Issues must be 7 days old.
  • Agendas have many Proposals and a meeting date
  • Tags have many Issues through join model
  • Categories have many Issues through join model
  • Votes belong to an Issue or Amendment, a Character and an Account, are timestamped, and indicate positive or negative voting intent
  • WatchedIssues belong to a user and an issue and are a list of users watching an issue
  • Characters belong to an Account
  • Accounts belong to a User and contain an API ID / key, and have many characters. API keys will be encrypted using a symmetric key stored outside of SCM. This table should still be altered before publishing DB snapshots to remove or fuzz API keys and UIDs.
  • Users have many accounts and votes through accounts

Remember issue merge options, big picture mode. <- Avoid issue merging! Issue merging doesn’t make any sense. Referencing is provisioned for.

Technical Details

  • Framework: Ruby on Rails. Ruby’s an easy one to learn for those who don’t know it, Rails makes the work fast and we’ve got plenty of Rails devs already. Good tool support, too- lots of the feature work is off-the-shelf from the Rails ecosystem.
  • Host: Spare VPS, Ix has one that can run this and the DB server/search server
  • Search: Sphinx. The damn thing is awesome. Chribba uses it for EVE Search, EVE Metrics uses it, so plenty of knowledgebase to build on.
  • Database: PostgreSQL, again awesome and already got it ready to go
  • Testing: Pre-deploy continuous integration, unit test, TDD for user stories. Rspec for testing, CI can run on one of Ix’s development boxes via a postcommit hook and upload to a VPS for HTML reports.
  • Email: Postfix. It just works.

User Stories

CSM

  • Update a Proposal’s Status
  • Make a Proposal (Why would this be any different that what regular users do? Does it need an entry here?)
  • Approve Amendment
  • Moderate Users (?)
  • Moderate Issues (?)
    • Marking as duplicate by creating a reference between issues and marking the ‘from’ issue of that reference as a duplicate (hides from public lists, still visible via reference link on main issue)
    • (For now, removing this and replacing with item above) Merge Issue/Proposal (Q: how would votes from same user on >1 merged issues get dealt with? Extra votes from same user simply dropped? Yeah, merged issue gets all votes from both issues but not twice from the same user)
  • Make an Agenda (allow proposals to be one-click added to agenda)
  • Update Keywords (Does this mean Categories?)
  • Propose polls, to parley the voting functionality into straw polls on topics of interest? (Note: This was done in the AH for the nano nerf, with a “For” thread and an “Against” thread)

Players

  • Log in
  • Register
  • Add an API key and select voting character
  • Add additional API keys and select voting character
  • Submit a Proposal
  • Vote Proposals Up or Down
  • Comment on Proposals
  • Search for Proposals
  • Search for Proposals by tag + multiple tags
  • Search for Proposals by category
  • Search for Proposals by date
  • Vote on Amendment
  • Recommend Amendments
  • Approve Amendments for Proposals they own
  • Propose/approve a Proposals merger of a Proposals they own with the owner of another related Proposals?
  • Cross reference similar or duplicate Proposals (duplicates should perhaps have the votes combined, if the votes do not come from the same user; question: combined on both?) (or duplicates can be added as ammendments to the current main Proposal)(possible/desired to allow users to transfer votes to another issue in one action rather than requiring two actions, e.g., down vote here, go upvote there?) My favorite option so far is amenedment/rejection. Also all Proposals are independent of one another, so vote transferral makes no sense.
  • Sort Proposals by tag, submission date, title keyword, submitter (more potential fields listed under the API section above)

Ideas to Consider in the Future

Please keep this section last in the document

  1. CSM Blog
    • Posts require Author + 2 other CSM to approve for publishing
    • Would act as a semi-official central CSM blog
    • Allow individual CSMs to make individual posts?
Add a custom footer
Add a custom sidebar
Clone this wiki locally