Skip to content

Commit 959971c

Browse files
arsalansufiarsalansufi
authored
Clean up READMEs in prep for cert (#5635)
* Update top-level and app-level READMEs * Update docs/ in prep for cert - Use a permalink instead of a downloaded PDF for the TS style guide and also pull the latest - Update the permalink for the Rust style guide to pull the latest - Reorder the rust.md * Move vxsuite-complete-system acknowledgments into CONTRIBUTORS.md * A few more misc edits * Remove some outdated docs in need of revamping We'll revisit docs like a writing style guide and external contributing guide, after we further discuss internally what those should look like * A few more misc edits
1 parent e71c89d commit 959971c

File tree

34 files changed

+260
-683
lines changed

34 files changed

+260
-683
lines changed

‎CONTRIBUTORS.md

+17-10
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,30 @@
11
# Contributors
22

3-
This document will evolve as we make sure to include all the
4-
contributors to the VotingWorks system.
3+
This document will evolve as we make sure to include all the contributors to the
4+
VotingWorks system.
55

66
## VotingWorks Pioneers
77

8-
VotingWorks has benefited from the input of dozens of election
9-
administrators around the country. Some of them were particularly
10-
helpful: they took a chance on VotingWorks at the pilot stage, when
11-
all we had were prototypes. They dealt with the pains of an
12-
in-development product and gave us critical feedback. VotingWorks
13-
wouldn't be VotingWorks without them.
8+
VotingWorks has benefited from the input of dozens of election administrators
9+
around the country. Some of them were particularly helpful: they took a chance
10+
on VotingWorks at the pilot stage, when all we had were prototypes. They dealt
11+
with the pains of an in-development product and gave us critical feedback.
12+
VotingWorks wouldn't be VotingWorks without them.
1413

1514
In Choctaw County, Mississippi: Amy Burdine and Dr. Wayne McLeod
1615

17-
In Warren County, Mississippi: Jan Daigre, Sara Dionne, Donald Oakes, Shelley Plett, Joe Tom
16+
In Warren County, Mississippi: Jan Daigre, Sara Dionne, Donald Oakes, Shelley
17+
Plett, Joe Tom
1818

1919
In Calhoun County, Mississippi: Carlton Baker
2020

2121
In Woodstock, New Hampshire: Judy Welch and Ken Chapman
2222

23-
In Moultonborough, New Hampshire: Julia Marchand and Paul Punturieri
23+
In Moultonborough, New Hampshire: Julia Marchand and Paul Punturieri
24+
25+
## Security Architecture
26+
27+
Trammell Hudson (@osresearch) for support on our TPM and dm-verity integrations
28+
29+
Matthew Garrett (@mjg59) for providing feedback on our security architecture and
30+
helping us iron out our Secure Boot policies

‎README.md

+21-8
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,29 @@
1-
# vxsuite
1+
# VxSuite
22

3-
The VotingWorks in-person voting system.
3+
The core of the VotingWorks paper-ballot voting system.
44

55
## About
66

7-
Includes software for a [ballot-marking device (BMD)](./apps/mark/frontend), a
8-
[ballot scanning device (BSD)](./apps/central-scan/frontend), a
9-
[precinct scanner](./apps/scan/frontend), and an
10-
[election manager](./apps/admin/frontend). See https://voting.works for more
11-
information about VotingWorks.
7+
Includes software for:
128

13-
## Development & Build
9+
- [VxAdmin](./apps/admin/frontend) — An offline central election manager laptop
10+
- [VxCentralScan](./apps/central-scan/frontend) — A central scanner for batch
11+
scanning of ballots, often used for absentee ballot processing
12+
- [VxMark](./apps/mark-scan/frontend) — A fully accessible ballot-marking device
13+
(BMD)
14+
- [VxScan](./apps/scan/frontend) — A precinct scanner for casting of ballots
15+
(marked by hand or by BMD)
16+
- [VxDesign](./apps/design/frontend) — An application for designing ballots
17+
18+
VxAdmin and VxCentralScan comprise the "central system." VxMark and VxScan
19+
comprise the "precinct system."
20+
21+
VxDesign exists separate from the other apps and is managed by VotingWorks
22+
rather than deployed on hardware into locales.
23+
24+
See https://voting.works for more information about VotingWorks.
25+
26+
## Development
1427

1528
See the [developer documentation](./docs/development.md).
1629

‎apps/admin/backend/README.md

+4-18
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,5 @@
1-
# Admin Module
1+
# VxAdmin Backend
22

3-
## Setup
4-
5-
Follow the instructions in the [VxSuite README](../../../README.md) to get set
6-
up. This service is intended to be run as part of the VxAdmin stack and is used
7-
by the `election-manager` frontend, not run on its own. To run it as part of
8-
VxAdmin, run this:
9-
10-
```sh
11-
# in apps/admin/frontend
12-
pnpm start
13-
```
14-
15-
## Testing
16-
17-
```sh
18-
pnpm test
19-
```
3+
This backend is used by the [VxAdmin frontend](../frontend) and isn't intended
4+
to be run on its own. The best way to develop on the backend is by running the
5+
frontend.

‎apps/admin/frontend/README.md

+4-5
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
# Election Manager (VxAdmin)
1+
# VxAdmin
22

3-
This app is intended to be used on an offline computer by system administrators
4-
and election managers.
3+
An offline central election manager laptop.
54

65
Note: Election manager can refer to VxAdmin or a user role, depending on the
76
context.
@@ -12,11 +11,11 @@ Follow the instructions in the [VxSuite README](../../../README.md) to get set
1211
up, then run the app like so:
1312

1413
```sh
15-
# in apps/admin/frontend
14+
# In apps/admin/frontend
1615
pnpm start
1716
```
1817

19-
The server will be available at http://localhost:3000/.
18+
The server will be available at http://localhost:3000.
2019

2120
## Testing
2221

‎apps/central-scan/backend/README.md

+3-74
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,5 @@
11
# VxCentralScan Backend
22

3-
Backend server for VxCentralScan.
4-
5-
## Setup
6-
7-
Follow the instructions in the [VxSuite README](../../../README.md) to get set
8-
up, then start up the VxCentralScan (`apps/central-scan`) frontend. You
9-
generally should not need to run this service directly. Instead, run like so:
10-
11-
```sh
12-
cd apps/central-scan/frontend
13-
pnpm start
14-
```
15-
16-
The commands to run the service below assume you'll be running them in a
17-
frontend, not this service directly.
18-
19-
## Mock Scanning
20-
21-
```sh
22-
# single batch with single sheet
23-
MOCK_SCANNER_FILES=front.jpeg,back.jpeg pnpm start
24-
25-
# single batch with multiple sheets
26-
MOCK_SCANNER_FILES=front-01.jpeg,back-01.jpeg,front-02.jpeg,back-02.jpeg pnpm start
27-
28-
# multiple batches with one sheet each (note ",," batch separator)
29-
MOCK_SCANNER_FILES=front-01.jpeg,back-01.jpeg,,front-02.jpeg,back-02.jpeg pnpm start
30-
31-
# use a manifest file
32-
cat <<EOS > manifest
33-
# first batch (this is a comment)
34-
front-01.jpeg
35-
back-01.jpeg
36-
37-
# second batch
38-
front-02.jpeg
39-
back-02.jpeg
40-
EOS
41-
MOCK_SCANNER_FILES=@manifest pnpm start
42-
43-
# scanning from an election backup file
44-
./bin/extract-backup /path/to/election-backup.zip
45-
MOCK_SCANNER_FILES=@/path/to/election-backup/manifest pnpm start
46-
```
47-
48-
If you are seeing unhandled promise rejection errors you may have an issue with
49-
where your image files are located, try moving them into the local scope of the
50-
app.
51-
52-
### Testing Adjudication
53-
54-
To force `requires_adjudication` of ballots, run this in
55-
`apps/central-scan/backend`:
56-
57-
```
58-
sqlite3 dev-workspace/ballots.db 'update sheets set requires_adjudication = 1;'
59-
```
60-
61-
## Switching Workspaces
62-
63-
By default a `ballots.db` file and a `ballot-images` directory will be created
64-
in a `dev-workspace` folder inside `apps/central-scan/backend` when running this
65-
service. To choose another location, set `SCAN_WORKSPACE` to the path to another
66-
folder:
67-
68-
```sh
69-
SCAN_WORKSPACE=/path/to/workspace pnpm start
70-
```
71-
72-
## Testing
73-
74-
```sh
75-
pnpm test
76-
```
3+
This backend is used by the [VxCentralScan frontend](../frontend) and isn't
4+
intended to be run on its own. The best way to develop on the backend is by
5+
running the frontend.

‎apps/central-scan/frontend/README.md

+48-8
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,65 @@
1-
# VotingWorks Batch Scanner (VxCentralScan)
1+
# VxCentralScan
22

3-
Scans ballots in batches using COTS (Commercial-off-the-Shelf) Fujitsu scanners.
3+
A central scanner for batch scanning of ballots, often used for absentee ballot
4+
processing.
45

56
## Setup
67

78
Follow the instructions in the [VxSuite README](../../../README.md) to get set
89
up, then run the app like so:
910

1011
```sh
11-
# in apps/central-scan/frontend
12+
# In apps/central-scan/frontend
1213
pnpm start
1314
```
1415

15-
The server will be available at http://localhost:3000/.
16-
17-
To scan ballots without scanner hardware use the `MOCK_SCANNER_FILES`
18-
environment variable set as described in
19-
[`apps/central-scan/backend`](../backend).
16+
The server will be available at http://localhost:3000.
2017

2118
## Testing
2219

2320
```sh
2421
pnpm test
2522
```
23+
24+
## Development Tips
25+
26+
### Mock Scanning
27+
28+
To scan ballots without scanner hardware, use the `MOCK_SCANNER_FILES`
29+
environment variable.
30+
31+
```sh
32+
# Single batch with single sheet
33+
MOCK_SCANNER_FILES=front.jpeg,back.jpeg pnpm start
34+
35+
# Single batch with multiple sheets
36+
MOCK_SCANNER_FILES=front-01.jpeg,back-01.jpeg,front-02.jpeg,back-02.jpeg pnpm start
37+
38+
# Multiple batches with one sheet each (note ",," batch separator)
39+
MOCK_SCANNER_FILES=front-01.jpeg,back-01.jpeg,,front-02.jpeg,back-02.jpeg pnpm start
40+
41+
# Use a manifest file
42+
cat <<EOS > manifest
43+
# First batch (this is a comment)
44+
front-01.jpeg
45+
back-01.jpeg
46+
47+
# Second batch
48+
front-02.jpeg
49+
back-02.jpeg
50+
EOS
51+
MOCK_SCANNER_FILES=@manifest pnpm start
52+
53+
# Use an election backup file
54+
./bin/extract-backup /path/to/election-backup.zip
55+
MOCK_SCANNER_FILES=@/path/to/election-backup/manifest pnpm start
56+
```
57+
58+
### Testing Adjudication
59+
60+
To force `requires_adjudication` of ballots, run this in
61+
`apps/central-scan/backend`:
62+
63+
```
64+
sqlite3 dev-workspace/ballots.db 'update sheets set requires_adjudication = 1;'
65+
```

‎apps/central-scan/integration-testing/README.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1-
# VxMark Integration Testing
1+
# VxCentralScan Integration Testing
22

3-
Integration tests for VxMark using the backend (`apps/mark/backend`), frontend
4-
(`apps/mark/frontend`), and dependent services.
3+
Integration tests for VxCentralScan using the backend
4+
(`apps/central-scan/backend`), frontend (`apps/central-scan/frontend`), and
5+
dependent services.
56

67
## Development
78

‎apps/design/backend/README.md

+4-40
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,5 @@
1-
# VxDesign (Backend)
1+
# VxDesign Backend
22

3-
Backend server for VxDesign.
4-
5-
## Setup
6-
7-
Follow the instructions in the [VxSuite README](../../README.md) to get set up,
8-
9-
You generally should not need to run the backend directly. Instead, run the
10-
frontend, which will automatically run the backend.
11-
12-
```sh
13-
cd apps/design/frontend
14-
pnpm start
15-
```
16-
17-
### Google Cloud Authentication
18-
19-
Follow the instructions
20-
[here](./src/language_and_audio/README.md#google-cloud-authentication) to
21-
authenticate with Google Cloud for language and audio file generation.
22-
23-
## Configuration
24-
25-
There are a few environment variables that can be set to configure the backend.
26-
27-
### `WORKSPACE`
28-
29-
By default a `design-backend.db` file will be created in a `dev-workspace`
30-
folder inside `apps/design/backend` when running the app. To choose another
31-
location, set `WORKSPACE` to the path to another folder:
32-
33-
```sh
34-
WORKSPACE=/path/to/workspace pnpm start
35-
```
36-
37-
## Testing
38-
39-
```sh
40-
pnpm test
41-
```
3+
This backend is used by the [VxDesign frontend](../frontend) and isn't intended
4+
to be run on its own. The best way to develop on the backend is by running the
5+
frontend.

‎apps/design/frontend/README.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,11 @@ Follow the instructions in the [VxSuite README](../../README.md) to get set up,
88
then run the app like so:
99

1010
```sh
11+
# In apps/design/frontend
1112
pnpm start
1213
```
1314

14-
The server will be available at http://localhost:3000/.
15+
The server will be available at http://localhost:3000.
1516

1617
### Google Cloud Authentication
1718

0 commit comments

Comments
 (0)