Updated readme with better branch information.
[selectricity] / README
1 ===============================================
2 === Getting Selectricity ======================
3 ===============================================
4
5 Selectricity is free software and is distributed under the GNU Affero
6 General Public License version 3. You are free to use, modify, and
7 distribute, or rework Selectricity under the terms of that license. Of
8 course, we'd sure like it if you would send fixes back to us and tell us
9 about cool stuff you do with our software!
10
11 The best way to get Selectricity is just to download it from our source
12 source repository. You'll need the Git version control system or
13 source control manager to check it. You can get it here:
14
15   http://git-scm.com/
16
17 Once you have it, getting the source code is pretty easy. You just need
18 to check out a branch with a command like this:
19
20   git clone http://projects.mako.cc/source/selectricity/.git
21
22 By default, this will create a working copy with the latest
23 *development* version of our code. If you want the latest production
24 version (i.e., what we're running on the site), you need to switch to
25 the live version of the software which is kept in a branch called
26 "live." Once you cloned the repository above, you can switch into the
27 directory (i.e., run "cd selectricity") and then run the following
28 command:
29
30   git checkout -b live origin/live
31
32
33 ===============================================
34 === Dependencies ==============================
35 ===============================================
36
37 To use Selectricity, you'll need to install the following gems in
38 addition to Ruby on Rails (gem:rails), MySQL (gem:mysql), and its
39 dependencies:
40
41  * rmagick
42  * gruff (http://nubyonrails.com/pages/gruff)
43  * sparklines (http://nubyonrails.com/pages/sparklines)
44
45 To use Selectricity in development mode, you'll need to install the
46 following gems:
47
48  * ruby-debug
49
50 Also, you will need install the other applications installed first:
51
52  * imagemagick (http://www.imagemagick.org/)
53
54 On Ubuntu, you can install install the dependencies with: 
55   apt-get install imagemagick libmagick9-dev ruby1.8-dev libwmf-bin rdoc \
56   libopenssl-ruby1.8 libreadline-ruby1.8 libmysqlclient15-dev
57
58 Our server configuration uses Mongrel (installed from gems) behind an
59 Apache2 load balancing proxy using mod_proxy.
60
61
62 ===============================================
63 === Contributors to Selectricity Include ======
64 ===============================================
65
66  * Benjamin Mako Hill <mako@atdot.cc>
67  * John Dong          <jdong@ubuntu.com>
68  * Justin Sharps      <jlsharps@mit.edu>
69
70 ===============================================
71 === Log =======================================
72 ===============================================
73
74 07/31/07
75 jlsharps: I've added a user authentication system known as
76 "acts_as_authenticated" to the code. The plugin is the the vendor/plugins 
77 directory. The two most noticeable changes are the AccountController and a 
78 redone User model. I've left the UserController in place for now, but the 
79 AccountController works in a different manner, so am switching over to that 
80 gradually. I saved the 5 lines or so in the old User model, overwrote 
81 it with the authenticated generator and then recopied the old stuff back in: 
82 has_many :elections and the name() method. The generator also creates its own 
83 migration file, but since we are using a create.sql file I adopted the 
84 migration file into a new users table in the create.sql file. I have yet to 
85 delete the old table because I haven't fully combed through the code yet and 
86 determined how many of the old attributes (such as first_name, last_name) may 
87 need to be retained. 
88 http://technoweenie.stikipad.com/plugins/show/Acts+as+Authenticated is the 
89 best site for documentation regarding acts_as_authenticaed. Also, currently
90 it only stores the user_id in the session, but i just found a guide to help 
91 me make it store the entire user object, so I'll do that while my battery 
92 charges.
93
94 08/03/07
95 Handy trick: use the command 'gem_server' from a shell to create a server at 
96 http://localhost:8008 that is an easy to navigate locally-hosted website with 
97 all the documentation on local gems you have in a easy to read format.
98
99 jlsharps: I added the Gruff plug-in today, which is viewable under the folder
100 vender/plugins/gruff.  I installed it directly using the Gruff plug-in and
101 included controller generate utility. The version 0.1.2, which doesn't seem to
102 be the latest version. I've looked into it and it see and it seems that the
103 latest version is 0.2.8. However, I wasn't sure how including a gem w/o a plugin 
104 would function in end-game rails so I just what I used for now. If you guys 
105 (mako of john) know how to do it, it'd probably be better to upgrade, but it 
106 didn't seem like the best use of my time right now.  I got the plug-in here:
107 http://topfunky.net/svn/plugins/gruff. You can get the gruff gem v 0.2.8 by 
108 typing "sudo gem install gruff", I believe it's also hosted on RubyForge. 
109
110 I created the GraphsController for Gruff methods to use. In Pollarize I put them 
111 in the ApplicationContorller file, so they would be accessible to all. While 
112 that it also an option here, it would also mean there wouldn't be much room for 
113 playing around because everything in the Application file has to be perfect or 
114 it seems to throw Error Code 500 (basically everything breaks). The show() 
115 is a sample sample provided with Gruff. 
116
117 Documentation is here:http://gruff.rubyforge.org/  Alternately, if you have the 
118 gem installed, you can use the ri command, or the above mentioned gem_server. 
119
120 If you guys want more helpful stuff here, let me know.
121
122 ======================================
123 === XML-RPC INFO                    ==
124 ======================================
125
126 The XML-RPC API is still under development, but is somewhat functional already:
127
128 To instantiate a client in Ruby, try something like:
129 client=ActionWebService::Client::XmlRpc.new(SelectricityAPI,"http://localhost:3000/selectricity_service/vote")
130
131
132 Getting the results of a quickvote is quite simple:
133 ?> client.get_quickvote_results("test")
134 => #<VoteResultStruct:0x336f92c @approval_winners=[1, 2], @borda_winners=[1], @plurality_winners=[1], @ssd_winners=[1], @errors=[], @condorcet_winners=[1]>
135
136 Casting a quickvote:
137 client.cast_quickvote("test",1,[[1,2]])
138
139 To figure out what you're voting for:
140 >> client.get_quickvote_candidate_map("test")=> #<CandidateMap:0x335bbc0 @errors=[], @candidate_names=["test", "test2"], @candidate_ids=[1, 2]>
141
142
143
144
145

Benjamin Mako Hill || Want to submit a patch?