Document README files (#312)

* readme for the bulletin_board api client * complete server readme * voting schemes readmes * fix typos * Update bulletin_board/ruby-client/README.md Co-authored-by: Andrés Pereira de Lucena <[email protected]> * Update bulletin_board/ruby-client/README.md Co-authored-by: Andrés Pereira de Lucena <[email protected]> * Update bulletin_board/ruby-client/README.md Co-authored-by: Andrés Pereira de Lucena <[email protected]> * Update bulletin_board/ruby-client/README.md Co-authored-by: Andrés Pereira de Lucena <[email protected]> * Update bulletin_board/ruby-client/README.md Co-authored-by: Andrés Pereira de Lucena <[email protected]> --------- Co-authored-by: Andrés Pereira de Lucena <[email protected]>
decidim · Jan 11, 2024 · b80e7e3 · b80e7e3
1 parent 46faa76
commit b80e7e3
Show file tree

Hide file tree

Showing 4 changed files with 70 additions and 37 deletions.
diff --git a/bulletin_board/ruby-client/README.md b/bulletin_board/ruby-client/README.md
@@ -1,34 +1,50 @@
 # Decidim::BulletinBoard
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/decidim/bulletin_board`. To experiment with that code, run `bin/console` for an interactive prompt.
+The Bulletin Board is a service composed by an Encryption Engine and an Append-Only Log. External queries to the Encryption Engine are allowed through a GraphQL API (see https://github.com/decidim/decidim-bulletin-board).
 
-TODO: Delete this and the text above, and describe your gem
+This gem provides a collection of commands to interact with such API using Ruby, mainly for its use in a backend service.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Run this command to add the gem to your Gemfile:
 
-```ruby
-gem 'decidim-bulletin_board'
+```console
+bundle add decidim-bulletin_board
 ```
 
-And then execute:
-
-    $ bundle install
-
 Or install it yourself as:
 
-    $ gem install decidim-bulletin_board
+```console
+gem install decidim-bulletin_board
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+Basic usage involves creating a client and using it to perform the desired operations:
+
+```ruby
+# Instantiate a client
+bulletin_board = Decidim::BulletinBoard::Client.new
+
+# Perform operations
+bulletin_board.cast_vote(election_id, voter_id, encrypted_data) do |message_id|
+  # Do something else with the message_id
+end
+```
+
+See a list of available operations here: https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/ruby-client/lib/decidim/bulletin_board/client.rb
+
+This module is used by the module Decidim Elections, check it out here: 
+
+- https://github.com/decidim/decidim/tree/develop/decidim-elections
 
-## Development
+Usage examples:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+- https://github.com/decidim/decidim/blob/develop/decidim-elections/lib/decidim/elections.rb
+- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/commands/decidim/elections/voter/cast_vote.rb
+- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/commands/decidim/elections/voter/update_vote_status.rb
+- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/commands/decidim/elections/admin/setup_election.rb
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

diff --git a/bulletin_board/server/README.md b/bulletin_board/server/README.md
@@ -9,41 +9,57 @@ The Bulletin Board is a service composed by an Encryption Engine and an Append-O
 - System dependencies:
 - Python gmpy2 package dependencies: libgmp, libmpfr and libmpc
 
-The Bulletin Board depends on the existence of a Decidim installation.
+The Bulletin Board is intended to use alongside a Decidim installation. Its main purpose is to provide a GraphQL interface to a secure, auditable and verifiable voting system. This is currently achieved by using the [ElectionGuard python implementation](https://github.com/microsoft/electionguard-python), developed by Microsoft. So this server acts as a [wrapper to the ElectionGuard python code](../../voting_schemes/electionguard/python-wrapper).
 
-- Installation:
+See how python code is executed using PyCall here:
+- https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/server/app/services/voting_scheme/electionguard/voter.rb
+- https://github.com/decidim/decidim-bulletin-board/blob/develop/bulletin_board/server/app/services/voting_scheme/electionguard/bulletin_board.rb
+
+Please check the [main documentation](../../README.adoc) for this repository for more convenient ways to run the Bulletin Board.
+
+## Installation:
 
 First, clone the repository and enter in the new folder:
 
-```
+```bash
 git clone [email protected]:decidim/decidim-bulletin-board.git
 cd decidim-bulletin-board/server
 ```
 
 Now, execute these commands:
 
-```
+```bash
 bundle install
 npm install
 rails db:create
 rails db:migrate
 ```
 
-- How to run the rubocop linter
+## Run the server
 
+```bash
+bin/rails server
 ```
+
+Conect to the GraphQL interface in http://localhost:3000/api (documentation is embedded)
+
+## other commands
+
+- How to run the rubocop linter
+
+```bash
 bundle exec rubocop
 ```
 
 - How to run the test suite
 
-```
+```bash
 bundle exec rspec
 ```
 
 - How to update the GraphQL schema definition run:
 
-```
+```bash
 bundle exec rake schema:generate
 npm run schema:generate
 ```

diff --git a/voting_schemes/dummy/ruby-adapter/README.md b/voting_schemes/dummy/ruby-adapter/README.md
@@ -1,8 +1,6 @@
 # VotingSchemes::Dummy
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/voting_schemes/dummy`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+The Bulletin Board is a generic API for storing and retrieving ballots and tallies for elections. The final implementation of the protocol used for creating an election may vary. This gem provides a dummy implementation for testing purposes.
 
 ## Installation
 
@@ -22,14 +20,14 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+This implementation is intended for testing purposes only. It allows to test the Bulletin Board without the need to use a fully configured Decidim installation.
+It also skips the encryption and decryption steps, so it is not suitable for production use.
 
-## Development
+You can [start the server](../../bulletin_board/server) in development mode and connect to the built-in testing admin sandbox at:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+http://localhost:3000/sandbox
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/voting_schemes-dummy.
+Bug reports and pull requests are welcome on GitHub at https://github.com/decidim/decidim-bulletin-board/issues.
diff --git a/voting_schemes/electionguard/ruby-adapter/README.md b/voting_schemes/electionguard/ruby-adapter/README.md
@@ -1,8 +1,13 @@
 # VotingSchemes::Electionguard
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/voting_schemes/electionguard`. To experiment with that code, run `bin/console` for an interactive prompt.
+The Bulletin Board is a generic API for storing and retrieving ballots and tallies for elections. The final implementation of the protocol used for creating an election may vary. This gem provides the [Microsoft's ElectionGuard](https://github.com/microsoft/electionguard-python) Javascript implementation for production use in Decidim.
 
-TODO: Delete this and the text above, and describe your gem
+Note that the ElectionGuard implementation works by using two different wrappers around Electionguard:
+
+- A [Python Wrapper](../python-wrapper) for its use in the backend of the [GraphQL API server](../../../bulletin_board/server).
+- A [Javascript Wrapper](../js-adapter) that compiles the whole Electionguard python app into web-assembly and allows to use it in the frontend (this ensure that the voting process is not tampered by sending any data to the backend).
+
+This gem provides a very simple gem that wraps the Javascript implementation and allows to use it in the frontend of a Decidim application (Elections module).
 
 ## Installation
 
@@ -22,14 +27,12 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
-
-## Development
+You can see examples of usage by looking at the Decidim Elections module:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/packs/src/decidim/elections/voter/casting-vote.js
+- https://github.com/decidim/decidim/blob/develop/decidim-elections/app/packs/src/decidim/elections/election_log.js
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/voting_schemes-electionguard.
+Bug reports and pull requests are welcome on GitHub at https://github.com/decidim/decidim-bulletin-board.