From b80e7e320b46d63164c251eaee82f70e51dd4fcc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Verg=C3=A9s?= Date: Thu, 11 Jan 2024 15:53:01 +0100 Subject: [PATCH] Document README files (#312) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 * Update bulletin_board/ruby-client/README.md Co-authored-by: Andrés Pereira de Lucena * Update bulletin_board/ruby-client/README.md Co-authored-by: Andrés Pereira de Lucena * Update bulletin_board/ruby-client/README.md Co-authored-by: Andrés Pereira de Lucena * Update bulletin_board/ruby-client/README.md Co-authored-by: Andrés Pereira de Lucena --------- Co-authored-by: Andrés Pereira de Lucena --- bulletin_board/ruby-client/README.md | 44 +++++++++++++------ bulletin_board/server/README.md | 30 ++++++++++--- voting_schemes/dummy/ruby-adapter/README.md | 14 +++--- .../electionguard/ruby-adapter/README.md | 19 ++++---- 4 files changed, 70 insertions(+), 37 deletions(-) diff --git a/bulletin_board/ruby-client/README.md b/bulletin_board/ruby-client/README.md index f79fc683..60ae60f9 100644 --- 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 index ba046b57..cf136ced 100644 --- 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 git@github.com: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 index 28738422..18d66201 100644 --- 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 index 92985a5e..bb6ee9d0 100644 --- 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.