This file intends to explain how to organize an election (or a referendum). It's very verbose because I did not want to forget anything, but it's not that difficult

These instructions are written before anonymous voting is effective. Some of the steps (most probably steps 11 & 13) and the introduction will probably need to be updated later.

Notes:

• the foundation-announce and foundation-list mailing list archives are really useful to help you remember how things were done the previous years. The GNOME Foundation section of http://www.gnomedesktop.org is also useful.

• you can also look at the materials from previous elections, available on the Foundation website and in the elections/ directory of the gnome-foundation module.

• when a deadline approaches, sending a reminder is often useful.

Introduction: Explanation of the vote architecture

Votes for elections/referenda are done by e-mail: ballots are sent with instructions to the voters and voters use their votes using web based election system.

Election system uses mysql back-end for keeping election data. MySQL database uses election start date, and end date so results are generated immediately after election ends. MySQL database stores temporary tokens which is sent with ballots to use identifying voter. Every e-mail address has temporary token. After voter used his/her vote using system, an anonymous vote token is generated, and this one is also stored in database for voter to check their vote. This process is totally anonymous, there's no connection with e-mail address of voter and the vote token. After elections, voter can check if his/her vote is correct and/or counted using this hash, known by voter only.

When the ballots are sent, they contain the validation token. The voter then sends his vote, containing the validation token, to the vote mailing list. When the votes are counted, the validation token is used to identify the voter and determine if the vote is valid.

Note that voters should verify the results and their vote used to build the results. This adds another protection from errors.

Ask some informations to the Board (elections only)

Before preparing the elections, the Committee should ask the Board if the number of directors will change (see article VIII, section 2 of the by-laws).

Another information that is useful is the date that the outgoing board 'passes the baton' to the incoming board.

Prepare a timeline

A timeline for the elections/referendum should be prepared.

The timeline should contain:

• date of applications closed for elections/referendum
• date of renewals closed for elections/referendum
• date when the ballots are sent
• date of the end of the voting period
• tentative date for the preliminary results
• date when the challenges to the results close

For elections, the timeline should additionnaly contain:

• date when list of candidates opens
• date when list of candidates closes
• date of announce of the list of candidates
• dates in case of a tie

Be sure to make it crystal clear on which timezone the deadlines happen (it's usually UTC).

The timeline should be sent to the Board for comments before announcing the elections/referendum.

See for an elections timeline example: http://mail.gnome.org/archives/foundation-announce/2004-October/msg00004.html

See for a referendum timeline example: http://mail.gnome.org/archives/foundation-announce/2004-September/msg00001.html

Send renewal notices

Only members whose membership will still be valid at the end of the elections should be able to vote. Thus, members whose membership ends during the elections should renew their membership.

The renew-mailout.pl script should be used to send renewal notices. The script header explains how to use it.

You should send a second renewal notice for people who did not renew with the first renewal notice after two weeks (use the --reminder option for the script).

Announce the elections/referendum

Make sure every member is subscribed to foundation-announce

This is necessary to make sure that the members will receive the announce. To do so, you can use this one liner to generate a list of members addresses:

$ mysql -u dbuser -p -h button-back foundation -e 'select email from foundationmembers where resigned_on IS NULL' | awk ' /|/ { print $1 }'
> /tmp/email-list.txt

Now, you can go to http://mail.gnome.org/mailman/admin/foundation-announce/members/add. There, you can specify that the email list is in /tmp/email-list.txt (the file will be uploaded) and you should probably add this additional text:

This is an automatic subscription for the upcoming referendum.

If you receive this subscription notification, then it means that the
e-mail address being used to identify you as a GNOME Foundation member
wasn't subscribed to foundation-announce@gnome.org. If you do not wish
to use this e-mail address, please contact membership-committee@gnome.org
so the Committee can update your e-mail address.

Thanks,

It will usually subscribe 10-20 members to this list.

Create a calendar file for the timeline

This file will be made available on the website so people can subscribe it. You can use evolution to generate it.

Update the Foundation website

You can look at the directories of previous elections/referenda to see how it should be organized (the best example right now is http://cvs.gnome.org/viewcvs/foundation-web/foundation.gnome.org/elections/2004/).

You also need to modify http://cvs.gnome.org/viewcvs/foundation-web/foundation.gnome.org/elections/index.wml?view=log to link to the new elections (change "elections" to "referenda" in the path if it's a referendum).

At last, you'll need to add a news item to http://cvs.gnome.org/viewcvs/foundation-web/foundation.gnome.org/index.wml?view=log and http://cvs.gnome.org/viewcvs/foundation-web/foundation.gnome.org/news/index.wml?view=log.

Add a ChangeLog entry and commit your changes.

Write an announce e-mail

See for an elections announce example: http://mail.gnome.org/archives/foundation-announce/2004-October/msg00004.html

See for a referendum announce example: http://mail.gnome.org/archives/foundation-announce/2004-September/msg00001.html

Send the mail to foundation-announce and foundation-list.

Write a news item for gnomedesktop

See for an elections announce example: http://gnomedesktop.org/node/2001

See for a referendum announce example: http://gnomedesktop.org/node/1949

Process membership applications

This is a background task until the applications/renewals are closed for the elections/referendum.

All the applications/renewal sent before the closing date should be processed before the ballots are sent.

Make list of voters

A list of voters should be made available as soon as possible so members can verify that they are on the list and that their e-mail address is correct.

This step should be done in parallel with step 5: the list should be updated when you process some applications.

Until the list of voters is final, you should add a sentence like "This list is a temporary list and is not the final list of voters." to the WML file.

Here's are the steps needed to add this list:

• use htmlize-membership2.py from the gnome-foundation module like this:

  $ ./htmlize-membership2.py membership_new.txt > /tmp/voters.wml

• open /tmp/voters.wml your favorite text editor and perform these actions:

  • remove the contributions (%s/gt; (.*)<\/li>/gt;<\/li>/g with vim)

  • remove the <link> tags at the beginning

  • remove the <div id="body"> tag and the corresponding </div> tag

  • remove the sidebar, the hdr and the copyright sections
  • replace all occurences of "members" by "voters"

  • replace the <h1> title and the <title> title

  • change the e-mail address from membership-committee@gnome.org to elections@gnome.org

  • remove the "Current members" paragraph

  • verify that you have the correct number of voters. You can use this command line to know how many members there are:

    $ grep -v ^# membership_new.txt | wc -l

• the idea here is to have a voters.wml similar to the voters.wml of previous elections/referendum
• move /tmp/voters.wml in the right directory of the foundation-web module
• add voters.html in Makefile.am and in .cvsignore
• add voters.wml to cvs

• add a ChangeLog entry and commit

Do not forget to update the list when you process applications!

You should advertise this list by sending some e-mails on foundation-list to encourage members to verify it. When the list of voters becomes final, you should announce it on foundation-announce and foundation-list.

Announce list of candidates (elections only)

You should send an e-mail to foundation-announce and foundation-list when the deadline for candidacies is crossed. This will officially close the list of candidates. The next step is to announce the official list of candidates.

Before doing so, you should verify for each candidate that he/she:

• is a member of the Foundation
• has announced his/her candidacy on foundation-announce
• has told who is his/her employer

Then, you can add a candidates.wml file in the right directory of the foundation-web module. The simplest way to do this is to copy the file from the previous elections directory and modify the candidates. Don't forget to add candidates.html in Makefile.am and in .cvsignore.

You should commit this only once you know the full list of candidates. If you don't add candidates all at once, then you might end up with some news on some websites telling "Not enough candidates for the GNOME Foundation elections"...

Once you've committed the list of candidates, send an e-mail to foundation-announce and foundation-list. You can also announce the list of candidates on http://www.gnomedesktop.org.

See for an announce example:
http://mail.gnome.org/archives/foundation-announce/2003-November/msg00012.html
http://gnomedesktop.org/node/1439

Organize a debate

A debate is often needed to enable people to know how they will vote. For this reason, the Committee should try to organize a debate on foundation-list.

For the elections, we send some questions to the candidates. Since 2003, we ask the readers of gnomedesktop.org what questions they would like to see answered by the candidates (the gnomedesktop.org post is of course announced on foundation-announce and foundation-list). Someone then selects the 10 best questions and send them to the candidates. We usually ask a previous Board member to select the questions.

The debate should start after the list of candidates has been announced and last at least a week. Sending the ballot too early might hurt the debate (and it will possibly make it useless).

See for example these gnomedestktop.org archives:
http://gnomedesktop.org/node/2025
http://gnomedesktop.org/node/1428

Write the ballot

The ballot is of course a central part of the elections/referendum. Ballots are not really difficult to write: you usually copy the ballot from the previous elections/referendum and update it: change the dates, change the candidates (for elections) or the question (for referenda), etc.

For elections, be sure to append an ID number to each lines presenting a candidate. This will help the vote counter script. Such a line should look like this:

Candidate Name (ID# n)

(where n is an unique number for each candidate)

Try to make sure that the ballot is simple to understand.

You'll probably want to make it proofread, especially if you're not a native english speaker.

Ballots from previous elections/referenda are in the elections/ directory of the gnome-foundation module.

Prepare the vote mailing list

Close the archives

All votes are sent to the vote mailing list. When there's no elections/referendum, the archives of this mailing list are publicly available. This obviously can not be the cases when a vote is occuring.

Go to http://mail.gnome.org/mailman/admin/vote/archive and change the "archive_private" option to "private" and validate the change.

You should verify that the change works. For this, try to access the archives at http://mail.gnome.org/archives/vote/. If you can access the archives, then you need to contact a sysadmin so that he fixes the problem. You can reach the sysadmins on irc://irc.gnome.org/#sysadmins

Open the vote mailing list to everyone (no moderation)

The ballots need to be received without moderation.

To configure this option, go to http://mail.gnome.org/mailman/admin/vote/privacy/sender.

Change the "generic_nonmember_action" option to "accept" and validate the change.

Add an automatic reply

As voters can not look at the archives to check if their vote was received, we configure an automatic reply.

Go to http://mail.gnome.org/mailman/admin/vote/autoreply. Change the "autoresponse_postings_text" field to:

Your vote for the <name of elections|referendum> has been received.
Thank you for your interest in the GNOME Foundation

The GNOME Foundation Election & Membership Committee

Verify that the "autorespond_postings" option is set to "yes".

Send a test mail

To verify that you successfully configured the mailing list, send an e-mail to the vote mailing list from a non-subscribed address. You should receive the automatic reply you set and you should see the mail in the private archives (link available from the admin interface).

Send the ballots

Now you're ready to send the ballots. To do so, you will use the mail-ballots.pl script.

Update the script

The script contains the subject of the e-mail that voters will receive. As this subject contains the object of the vote, it needs to be updated. To do so, open mail-ballots.pl in your favorite text editor, search for "Subject: " and change the subject.

For example, the line should be Subject: Official Ballot for 2004 GNOME Foundation Elections for the 2004 elections.

Usage of the script

The script needs a mail transport agent to send the e-mails. If you don't have one or if you're not sure that your ISP allows you to directly send mails, it's probably better (and safer) to run the script from a gnome.org server.

The basic usage of the script is like this:

$ mail-ballots.pl voters.txt ballot.txt "thesecretstring"

You must have read the explanation of the vote architecture (step 11)) to fully understand the following.

voters.txt is a membership_new.txt-like file (same structure) that contains the voters. We don't use membership_new.txt as there might be members that applied too late for membership: the list of members can be larger than the list of voters. You should keep the list of voters somewhere because it is needed to build the results (step 13)).

ballot.txt is the ballot you wrote in step 9). Some special lines in the ballot will be rewritten:

• "Dear <member>" => "Dear <Member Name>"

• "Member:" => "Member: <Member Name>"

• "Member Address:" => "Member Address: <Member e-mail address>"

• "Validation Token:" => "Validation Token: <special token>"

You should make sure that the ballot contains at least these three last lines as they're what is used to validate the vote.

"thesecretstring" is a secret that you should not share: if this string is known, then anybody can craft the vote of any voter: since it's the only information that is not publicly known to build the validation token. However, you should keep it somewhere because it is needed to build the results (step 13)).

Test the script

The first thing to do is to verify that the scripts works. The simplest way to procede is to build a voters list that contains only yourself.

Run the script as explained in step 11) b) and wait for your ballot. If you don't receive the ballot, then you probably broke the script. You'll need to fix it... If you receive the ballot, then verify that it looks okay (pay attention to the "Member:", "Member Address:" and "Validation Token:" lines).

Use the script

If the script is working well, then you're ready to use it with the real list of voters, as explained in step 11) b).

You should keep the list of errors so you know which members did not receive a ballot. If possible, also try to keep the mail transport agent logs: they're very useful to verify that the ballots were delivered to the correct mail servers.

Send an announce

You'll need to send an e-mail to foundation-announce and foundation-list so voters know the ballots were sent and can ask you a new ballot if they did not receive their ballot.

See for an announce example: http://mail.gnome.org/archives/foundation-announce/2003-November/msg00014.html

If you need to resend a ballot

Some voters will probably ask you a new ballot. You can use the mail-ballots.pl script to send the new ballot as in step 11) d): you'll simply need to change the recipient list.

Some other voters will ask you to send a new ballot to an e-mail address that is not their registered e-mail address. You can do this with the resend-ballot.pl script.

Before using this script, edit it to change the mail subject (as in step 11) a)). Then you can send a new ballot to a member like this:

$ resend-ballot.pl ballot.txt "new@email.address" "Member Name" "Member e-mail address" "thesecretstring"

Note that "Member Name" and "Member e-mail address" must be the exact same strings than in membership_new.txt, without the "no_spam." in the address (it's case-sensitive). "thesecretstring" should be the same secret string as the one used in step 11) d).

End of voting period

Close the vote mailing list

Ballots should stop being accepted for the vote mailing list. Thus, we add the moderation back.

Go to http://mail.gnome.org/mailman/admin/vote/privacy/sender, change the "generic_nonmember_action" option to "hold" and validate the change.

Change the automatic reply

Voters that send their vote too late need to know the voting period has ended. The best way to do this is to change the automatic reply.

Go to http://mail.gnome.org/mailman/admin/vote/autoreply. Change the "autoresponse_postings_text" field to:

The vote period for the <name of elections|referendum> has ended.

Preliminary results will be announced as soon as possible, probably on
<date>.

Thank you for your interest in the GNOME Foundation

The GNOME Foundation Election and Membership Committee

Verify that the "autorespond_postings" option is set to "yes".

Send a test mail

To verify that you successfully configured the mailing list, send an e-mail to the vote mailing list from a non-subscribed address. You should receive the automatic reply you set and you should see that the mail does not appear in the private archives (link available from the admin interface).

Send an announce

Send an e-mail to foundation-announce and foundation-list to announce the voting period has ended.

See for an announce example: http://mail.gnome.org/archives/foundation-announce/2004-December/msg00001.html

Build the results

Obtain the vote archives

Go to the private archives (link available from http://mail.gnome.org/mailman/admin/vote) and download the mbox files for the voting period.

It's possible that the private archives are not accessible. If this happens, then you need to contact a sysadmin so that he fixes the problem or send you the archives. You can reach the sysadmins on irc://irc.gnome.org/#sysadmins

Clean the list of voters

Open the list of voters you made in step 11) and remove all the comments. You should have a file with only the voters left.

Update the software

Get the tarball used to verify the results for the previous elections/referendum (be sure to get the one for referendum if you're building the results of a referendum). These tarballs are available on the Foundation website. Extract the files from the tarball. Now, you'll need to update various files from this tarball:

• update secret.txt with the secret string you used in step 11)

• replace registered-voters.txt with the list of voters you made in step 13) b)

• remove vote-archives.diff for now

• open Makefile in your favorite text editor and change all occurences of the vote archives filenames. You can also comment, for now the lines that use wget to get the archives.

• open vote-counter.py and update the candidate_tuples variable for elections or the answer_tuples variable for a referendum. Note that the numbers in candidate_tuples should be the ID you selected for each candidate in step 9).

Now, you should create a vote-archives.mbox file by concatening the uncompressed mbox archives you got in step 13) a). Copy this vote-archives.mbox file to a vote-archives.mbox.orig file (you will need to modify vote-archives.mbox).

Run the software

Everything is now ready to run the software. You just have to run:

$ python vote-counter.py vote-archives.mbox `cat secret.txt` registered-voters.txt > results.txt

You will get the results in results.txt.

Now is the hard part: you will see some errors at the beginning of results.txt. You should remove most of those errors by modifying vote-archives.mbox. The most frequent errors are:

• mail that is not a vote. You should simply remove the mail from the file.
• more than the maximum number of candidates (for elections) or more than one answer (for a referendum). This is generally caused by HTML mails: in some HTML mails, the content is both in pure text format and in HTML format and so it appears twice. A solution is to remove the HTML part of the mail.
• no candidates/answer chosen. This can happen when there are some characters before the names of the chosen candidates or before the answer. You should remove those characters.
• invalid member name in the vote. This is most probably a problem with content encoding. Some names should be in UTF-8 and the encoding was lost somewhere. You should replace the invalid member name with the one that enables the good validation token to be built.

You can look at the vote-archives.diff of previous elections/referendum to see how to fix most of those problems.

If there is an error you can not fix (for example, a validation token that is really invalid), try to contact the voter to verify if it's really his vote.

You can then run the script again to get results with less errors. Usually, you'll correct some errors, run the script and look at the list of errors and start again.

Once you have removed all the errors you could remove, you will have your preliminary results at the end of results.txt. You should compare these results with the ones obtained by another member of the Committee. If they are the same, then you've finished.

Clean the tarball

You can now build the tarball that will be made available on the Foundation website. To do this, you should:

• build a diff of your final vote-archives.mbox and the original votes-archives.mbox:

  $ diff -u votes-archives.mbox.orig votes-archives.mbox > vote-archives.diff

• remove votes-archives.mbox.orig

• do make clean

• uncomment the wget lines in the Makefile

You should then have a directory with the same content as the one of the original tarball. Rename the directory so it has the good year (and month, for a referendum) in its name and make a tarball out of it.

Announce the preliminary results

Once you're sure the results are correct, it's time to announce the preliminary results. The results are not final yet so people can look at the votes and challenge the results.

Do not forget to specify in the various announces that these results are preliminary!

Announce the results on IRC

If you want to see some people eager to know the results, go in irc://irc.gnome.org/#gnome and tell everyone you're about to announce the elections/results. You can then do the following steps without committing anything to CVS and without sending an e-mail to have a good announce effect on IRC

Open the vote mailing list archives

When the preliminary results will be announced, everyone should be able to verify them. This implies that the vote mailing list archives are public.

Go to http://mail.gnome.org/mailman/admin/vote/archive. Change the "archive_private" option to "public" and validate the change.

You should verify that the change works. For this, try to access the archives at http://mail.gnome.org/archives/vote/. If you can not access the archives, then you need to contact a sysadmin so that he fixes the problem. You can reach the sysadmins on irc://irc.gnome.org/#sysadmins

Announce the results on the foundation website

You should create a preliminary-results.wml file and a verify.wml file in the right directory of the foundation-web module. The simplest way to do this is to copy the file from the previous elections directory and modify the results/instructions.

Don't forget to add preliminary-results.html and verify.html in Makefile.am and in .cvsignore.

You'll also need to add to the foundation website a tarball that contains everything that is needed to verify the results. This is the tarball you made in step 13) e). Please verify that simply typing 'make' in the directory from the extracted tarball builds the correct results before adding the tarball.

You'll probably want to add a news item to http://cvs.gnome.org/viewcvs/foundation-web/foundation.gnome.org/index.wml?view=log and http://cvs.gnome.org/viewcvs/foundation-web/foundation.gnome.org/news/index.wml?view=log.

You can commit this as soon as you finished or wait a bit in order to have a good announce effect on IRC

Announce the results on the mailing lists

This should be done after having committed the results to the foundation-web module. You should send the announce e-mail to foundation-announce and foundation-list.

See for an elections example: http://mail.gnome.org/archives/foundation-announce/2004-December/msg00003.html

See for a referendum example: http://mail.gnome.org/archives/foundation-announce/2004-October/msg00002.html

Announce the results elsewhere

You can also announce the preliminary results on various websites. A news item is usually submitted to http://www.gnomedesktop.org.

See for an elections example: http://gnomedesktop.org/node/2074

In case of a tie (elections only)

If there is a tie between some candidates, a run-off needs to be organized. This has never happened so far, but this is most probably like mini-elections: steps 7, 9, 10, 11, 12, 13 and 14 should simply be repeated.

Challenges

Voters can challenge the preliminary results during two weeks (in fact, it depends on the elections/referendum timeline) by sending a mail to the Committee explaining why they think the preliminary results are not correct. The Committee must resolve each challenge before being able to announce the officual results.

The decision of the Committee can not be challenged again, but the Committee should try to resolve the challenge in the most open way possible.

No real challenge were expressed so far, and it should not happen if the preliminary results are seriously verified before they are announced.

Announce the official results

Once the end of the challenge period is reached and every challenge was resolved, the official results can be announced.

Announce the results on the foundation website

You should add a news item to http://cvs.gnome.org/viewcvs/foundation-web/foundation.gnome.org/index.wml?view=log and http://cvs.gnome.org/viewcvs/foundation-web/foundation.gnome.org/news/index.wml?view=log.

For elections, the http://cvs.gnome.org/viewcvs/foundation-web/foundation.gnome.org/about/history/index.wml?view=log page should be updated by adding the previous board.

Then, at last, you should add to the index.wml for the elections/referendum materials that the results are archived there for public access (see index.wml of previous elections/referenda).

Add a ChangeLog entry and commit your changes.

Announce the results on the mailing lists

This should be done after having committed the results to the foundation-web module. You should send the announce e-mail to foundation-announce and foundation-list.

See for an elections example: http://mail.gnome.org/archives/foundation-announce/2004-December/msg00004.html

See for a referendum example: http://mail.gnome.org/archives/foundation-announce/2004-October/msg00003.html

Announce the results elsewhere

You can also announce the results on various websites. A news item is usually submitted to http://www.gnomedesktop.org.

See for a referendum example: http://gnomedesktop.org/node/1999