Skip to content

Improve the documentation #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
+19 −7
Draft

Improve the documentation #19

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d6376c
docs: add requirements section
jlenon7 Oct 30, 2023
f4696a9
docs: simple fix in ortography
jlenon7 Oct 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 19 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,30 @@ The name comes from Marie Jean Antoine Nicolas de Caritat, Marquis of Condorcet,
French philosopher and mathematician, notably known for championing an election
method that now named after him.

The goal of this project is to allow organisations of people working remotely to
cast votes is a secure and transparent way, using a git repository to collect and
The goal of this project is to allow organizations of people working remotely to
cast votes in a secure and transparent way, using a git repository to collect and
authenticate votes.

## Requirements

To be able to cast a vote or create a ballot you will
need the following tools:

- [Node.js v16+](https://nodejs.org)
- [git](https://git-scm.com)

If you want to cast a vote with GitHub verified signature
you will also need to install [PGP](https://www.openpgp.org/).
Later in the documentation we will check how to install PGP depending
Comment on lines +20 to +21
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PGP is a protocol, you can't install it – like you can't "install HTTP", that wouldn't mean anything. They would need a PGP-client, a gpg is what Caritat will expect.

on your device and how to setup your key, so if you are not familiar
with it we recommend skipping it for now.

## Usage

### Participate to a vote using Caritat

#### Node.js CLI

Requires [Node.js](https://nodejs.org) 16+ and [git](https://git-scm.com).

If the vote is setup on a GitHub pull request and you have
[`gh`](https://cli.github.com) locally installed and logged in to your GitHub
account:
Expand Down Expand Up @@ -105,7 +117,7 @@ documentation on how to use the API.
- not basing their vote in function of what other has voted (having the
instigator always vote first helps alleviate this issue).
- As a Voter, you need to trust the panel of Secret Holders for:
- not reconstitue the Vote Private Key before the vote closes.
- not reconstitute the Vote Private Key before the vote closes.
- not leaking the Vote Private Key before the vote closes (if they have
reconstructed it, which they should not do).
- not basing their vote in function of what other has voted (if they have
Expand Down Expand Up @@ -170,7 +182,7 @@ The two other files can be used to vote without parsing the YAML file.
Encrypting the ballot is necessary to ensure people voting early do not
interfere or influence folks voting after them. At the end of the vote, the
the Vote Private Key can be made public, so anyone can decrypt the ballots and verify
the result themself. Or it can decided that the Vote Private Key won't be shared in
the result themselves. Or it can decided that the Vote Private Key won't be shared in
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is correct, "anyone" would represent a single person, with a single self

order to keep the votes anonymous, and a large enough panel of Secret Holders
(depending on the vote settings) need to share their key parts, decrypt the
ballots, and share the vote result without disclosing the content of the ballots.
Expand Down Expand Up @@ -199,5 +211,5 @@ you have a quantum computer at home to break the RSA encryption).

The license makes no restrictions on how this tool should be used, but keep in
mind that, as any electronic voting system, it can only be trusted as long as
the unanonymized vote ballots are made public as soon as the vote closes, which
the un-anonymized vote ballots are made public as soon as the vote closes, which
may or may not be OK depending on the type of election you are using this for.