Upgrade packages, fix dead links, update specification (#348)

jungshadow · web-flow · commit 0f9922966913 · 2024-08-15T18:29:02.000-04:00
- Upgrade packages, fix dead links, update specification
- Update GitHub workflow to use pipenv
- Fix python version in action
- Update Pipfile to match GitHub python version for actions
- Update Makefile to remove install command
- Updated PR and release workflows (though not sure if the latter's used)
diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml
@@ -3,7 +3,7 @@ name: Validate Pull Request
 on: pull_request
 
 env:
-  PYTHON_VERSION: 3.8
+  PYTHON_VERSION: 3.10.14
 
 jobs:
   validate: 
@@ -16,9 +16,11 @@ jobs:
         uses: actions/setup-python@v1
         with:
           python-version: ${{ env.PYTHON_VERSION }}
+      - name: Install pipenv
+        run: pip install pipenv
       - name: Change Directory
         run: cd ${{ github.workspace }}
-      - name: Install MkDocs
-        run: make install
+      - name: Install packages
+        run: pipenv install
       - name: Lint
-        run: make lint
+        run: pipenv run make lint
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -6,7 +6,7 @@ on:
       - main
 
 env:
-  PYTHON_VERSION: 3.8
+  PYTHON_VERSION: 3.10.14
 
 jobs:
   publish: 
@@ -19,10 +19,12 @@ jobs:
         uses: actions/setup-python@v1
         with:
           python-version: ${{ env.PYTHON_VERSION }}
+      - name: Install pipenv
+        run: pip install pipenv
       - name: Change Directory
         run: cd ${{ github.workspace }}
-      - name: Install MkDocs
-        run: make install
+      - name: Install packages
+        run: pipenv install
       - name: Deploy
         run: make deploy
       - name: Zip Sample Data
diff --git a/Makefile b/Makefile
@@ -2,11 +2,6 @@
 
 all: install serve
 
-install:
-	pip install --upgrade pip
-	pip install -r requirements.txt
-	mkdocs --version
-
 lint:
 	mkdocs build
 
diff --git a/Pipfile b/Pipfile
@@ -0,0 +1,17 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+jinja2 = "*"
+mkdocs = "*"
+mkdocs-material = "*"
+mkdocs-mermaid2-plugin = "*"
+mkdocs-redirects = "*"
+
+[dev-packages]
+
+[requires]
+python_version = "3.10"
+python_full_version = "3.10.14"
diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/README.md b/README.md
@@ -16,6 +16,28 @@ ElectionGuard is always improving. To keep up with the latest, check our **[offi
 
 This repository is a living document to help everyone interact with ElectionGuard. The [official ElectionGuard site][election-guard-official-page] is built using the `/docs` folder and [mkdocs][mkdocs-official-site] with [mkdocs-material][material-mkdocs]. Ensure you have the Python 3.8 or newer installed and run `make` to install the dependencies and start the site.
 
+#### Setup
+
+This repo uses [pipenv](https://pipenv.pypa.io/en/latest/) for package and environment management. Disregard the `requirements.txt` file as it will be removed in a subsequent release.
+
+1. Install packages
+
+```sh
+pipenv install
+```
+
+1. Run `make build` command from within the virtualenv
+
+```sh
+pipenv run make build
+```
+
+1. Serve the site
+
+```sh
+pipenv run make serve
+```
+
 ### C ++
 
 An ElectionGuard Core implemented in C++ to support ballot encryption and all phases of the Guardian key and tally ceremonies, including creation of the election package and production of the election record.
diff --git a/docs/Reports/E2EVerifiability.md b/docs/Reports/E2EVerifiability.md
@@ -6,5 +6,5 @@ The report provides an overview of the ElectionGuard Pilot in the 2022 Franklin
 
 ![Cover Photo2][Cover-Photo-2]
 
-[EAC-Report]: /images/EAC%20Report%20Final.pdf
-[Cover-Photo-2]: /images/coverphoto.png "Cover Photo 2"
+[EAC-Report]: ../images/EAC%20Report%20Final.pdf
+[Cover-Photo-2]: ../images/coverphoto.png "Cover Photo 2"
diff --git a/docs/develop/Applications.md b/docs/develop/Applications.md
@@ -8,7 +8,7 @@ If you develop an app for ElectionGuard, we suggest you [utilize our badges][bad
 
 ### ElectionGuard Core
 
-An ElectionGuard Core is an application that implements the base level [features] such as Ballot Encryption by implementing them according to the specification. The internal examples of this are the Python and C++ reference implementations. There is a community example of this with the Java port done by the community. 
+An ElectionGuard Core is an application that implements the base level features such as Ballot Encryption by implementing them according to the specification. The internal examples of this are the Python and C++ reference implementations. There is a community example of this with the Java port done by the community. 
 
 ### Ballot Marking
 
@@ -50,13 +50,12 @@ The results of election can be displayed after an election is closed. An example
 A verifier app verifies an election is true and accurate by using the publicly published information about a completed election. At the close of an election using ElectionGuard, an election record should be created and made public. ElectionGuard encourages third parties to create their own verifiers and help verify election records. A basic example of a verifier can be found within the [electionguard-python repository][verifier], but  verifiers should aim to be as thorough as possible. After consuming the files in an election record, verifiers can validate everything from the key ceremony to the decryption since the election is end to end verifiable. 
 
 <!--Links-->
-[selections]: ../../overview/Glossary/#selection
-[plaintext-ballot]: ../../overview/Glossary/#plaintext-ballot
-[ciphertext-ballot]: ../../overview/Glossary/#ciphertext-ballot
-[cast-ballot]: ../../overview/Glossary/#cast-ballot
-[spoiled-ballot]: ../../overview/Glossary/#spoiled-ballot
-[badges]: ../Badges
-[features]: ../../overview/Features
+[selections]: ../overview/Glossary.md#selection
+[plaintext-ballot]: ../overview/Glossary.md#plaintext-ballot
+[ciphertext-ballot]: ../overview/Glossary.md#ciphertext-ballot
+[cast-ballot]: ../overview/Glossary.md#cast-ballot
+[spoiled-ballot]: ../overview/Glossary.md#spoiled-ballot
+[badges]: Badges.md
 [admin app]: https://github.com/microsoft/electionguard-ui/tree/main/packages/admin-app
 [result app ]: https://github.com/microsoft/electionguard-ui/tree/main/packages/result-app
 [api client]: https://github.com/microsoft/electionguard-ui/tree/main/packages/api-client
diff --git a/docs/develop/Badges.md b/docs/develop/Badges.md
@@ -24,7 +24,12 @@ For your convenience, these are some badges to add to your repository indicating
 
 [![ElectionGuard 2.0][badge-2.0]][spec]
 ```
-[![ElectionGuard 2.0](https://img.shields.io/badge/🗳%20ElectionGuard-v2.0-yellow)](https://www.electionguard.vote/spec)
+[![ElectionGuard 2.0](https://img.shields.io/badge/🗳%20ElectionGuard-v2.0-green)](https://www.electionguard.vote/spec)
+```
+
+[![ElectionGuard 2.1][badge-2.1]][spec]
+```
+[![ElectionGuard 2.1](https://img.shields.io/badge/🗳%20ElectionGuard-v2.1-green)](https://www.electionguard.vote/spec)
 ```
 
 <!-- Links -->
@@ -34,6 +39,7 @@ For your convenience, these are some badges to add to your repository indicating
 [badge-0.95]: https://img.shields.io/badge/🗳%20ElectionGuard-v0.95-green
 [badge-1.0]: https://img.shields.io/badge/🗳%20ElectionGuard-v1.0-green
 [badge-1.1]: https://img.shields.io/badge/🗳%20ElectionGuard-v1.1-green
-[badge-2.0]: https://img.shields.io/badge/🗳%20ElectionGuard-v2.0-yellow
+[badge-2.0]: https://img.shields.io/badge/🗳%20ElectionGuard-v2.0-green
+[badge-2.1]: https://img.shields.io/badge/🗳%20ElectionGuard-v2.1-green
 
 --8<-- "includes/abbreviations.md"
diff --git a/docs/develop/Data_Schema.md b/docs/develop/Data_Schema.md
@@ -38,8 +38,8 @@ Currently, JSON is used as the primary serialization format of the artifacts fro
 [shield-green-0.95]: https://img.shields.io/badge/🗳%20ElectionGuard-v0.95-green
 [json-schema]: https://json-schema.org/specification.html "Json Schema Specification"
 
-[election-record]: ../Election_Record
-[sample-data]: ../Sample_Data
+[election-record]: Election_Record.md
+[sample-data]: Sample_Data.md
 [manifest]: https://github.com/microsoft/electionguard/blob/main/data/1.91/schema/manifest.schema.json "Manifest Json Schema"
 [ciphertext_election_context]: https://github.com/microsoft/electionguard/blob/main/data/1.91/schema/ciphertext_election_context.schema.json "Ciphertext Election Context Json Schema"
 [election_constants]: https://github.com/microsoft/electionguard/blob/main/data/1.91/schema/election_constants.schema.json "Election Constants Json Schema"
diff --git a/docs/develop/Getting_Started.md b/docs/develop/Getting_Started.md
@@ -5,31 +5,26 @@ ElectionGuard as an SDK provides a specification and reference implementations w
 1. [**Create an app**][applications] using ElectionGuard
 2. [**Contribute**][contribute] to ElectionGuard's open source
 
-
 !!! tip
-    If you're having trouble understanding where to start, the **[architecture][architecture]** pages dive in a bit deeper. Take a look at **[versioning]** to get a good idea of what is still in progress.
-
-
+    If you're having trouble understanding where to start, take a look at **[versioning]** to get a good idea of what is still in progress.
 
 ## Create an App
 
 There are many different possible applications that can be created using ElectionGuard reference implementations or for ElectionGuard. A helpful starting list can be found within **[applications][applications]**. Feel free to use [badges][badges] to indicate which version of the specification the app was developed for. 
 
 ## Contribute to Open Source
 
-ElectionGuard is an open source platform and depends on an active community and ecosystem. The **[contribute][contribute]** page highlights some top level ways to contribute. For those that want to jump right in, take a look at our **[approach][approach]** and our **[repositories][repositories]**.
+ElectionGuard is an open source platform and depends on an active community and ecosystem. The **[contribute][contribute]** page highlights some top level ways to contribute. For those that want to jump right in, take a look at our **[repositories][repositories]**.
 
 !!! note
     Each repository houses the **in-depth developer documentation** for coding with the repositories.
 
 ![Code][code-image]
 
 [code-image]: ../images/undraw/code_1.svg "Two people sitting at a computer"
-[contribute]: ../../contribute
-[architecture]: ../Architecture
-[applications]: ../Applications
-[approach]: ../Approach
-[badges]: ../Badges
-[data-schema]: ../Data_Schema
-[repositories]: ../Repositories
-[versioning]: ../Versioning
+[contribute]: ../contribute/index.md
+[applications]: Applications.md
+[badges]: Badges.md
+[data-schema]: Data_Schema.md
+[repositories]: Repositories.md
+[versioning]: Versioning.md
diff --git a/docs/develop/Repositories.md b/docs/develop/Repositories.md
@@ -72,9 +72,9 @@ This UI application features several TypeScript packages as a monorepo, a versio
 [election-guard-python-documentation]: https://microsoft.github.io/electionguard-python/ "Election Guard Python documentation"
 [election-guard-cpp-source]: https://github.com/microsoft/electionguard-cpp "Election Guard C++ source code"
 
-[election-guard-spec-overview]: ../../spec "ElectionGuard Specification"
+[election-guard-spec-overview]: ../spec/index.md "ElectionGuard Specification"
 [election-guard-verifiability]: ../concepts/Verifiability.md "Election Guard Verifiability"
-[election-guard-post-election-audit]: ../Glossary/#post-election-audit "Election Guard Post-Election Audit"
+[election-guard-post-election-audit]: ../overview/Glossary.md#post-election-audit "Election Guard Post-Election Audit"
 
 [election-guard-api-source]: https://github.com/microsoft/electionguard-api-python "Election Guard Web API source code"
 [election-guard-ui-source]: https://github.com/microsoft/electionguard-ui "Election Guard UI source code"
diff --git a/docs/elections/College_Park_Maryland_2023.md b/docs/elections/College_Park_Maryland_2023.md
@@ -1,13 +1,13 @@
 ![ElectionGuard College Park Banner][College-Park-Banner]
 # ElectionGuard in the November 2023 College Park General Election
 
-This November will see College Park use the Hart VerityScan scanner with ElectionGuard in a similar configuration to what was used in the [Preston Idaho election in 2022](Preston_Idaho_2022.md). This year, voters will fill out ballots either by hand or using Hart's [Verity TouchWriter](https://www.youtube.com/watch?v=_GA0kzJrM-s). The official tally will be conducted with the Hart system, which will include mail-in ballots scanned with the VerityScan scanner but, because the voters were not present to collect the confirmation code receipt, will not be able to verify that their ballots were included.
+This November will see College Park use the Hart VerityScan scanner with ElectionGuard in a similar configuration to what was used in the [Preston Idaho election in 2022][preston-idaho-pilot]. This year, voters will fill out ballots either by hand or using Hart's [Verity TouchWriter](https://www.youtube.com/watch?v=_GA0kzJrM-s). The official tally will be conducted with the Hart system, which will include mail-in ballots scanned with the VerityScan scanner but, because the voters were not present to collect the confirmation code receipt, will not be able to verify that their ballots were included.
 
-!!! info "Vote by mail is a feature of the [ElectionGuard 2.0 Specification](/spec/#v20)"
+!!! info "Vote by mail is a feature of the [ElectionGuard 2.0 Specification][election-guard-spec-v2_0]"
 
 ## New Capabilities
 
-While the core Hart system and voting process will be identical to [the system used in Preston, Idaho](/docs/elections/Preston_Idaho_2022.md) the ElectionGuard software will be *almost* (see below) a full [implementation of the 2.0 specification](/docs/spec/index.md). It incorporates most of the new encryption structures, including a new implementation of guardian architecture and elimination of placeholder votes.  A fully new version of the admin and guardian software used to run the key and tally ceremonies has also been developed.
+While the core Hart system and voting process will be identical to [the system used in Preston, Idaho][preston-idaho-pilot] the ElectionGuard software will be *almost* (see below) a full [implementation of the 2.0 specification][election-guard-spec-v2_0]. It incorporates most of the new encryption structures, including a new implementation of guardian architecture and elimination of placeholder votes.  A fully new version of the admin and guardian software used to run the key and tally ceremonies has also been developed.
 
 The biggest new capability is a full implementation of thresholding. Thresholding enables a quorum of guardians to participate in a tally ceremony rather than requiring all guardians to be present. (College Park will be using 5 guardians with a quorum of 3 to be present to run the tally ceremony.) Each guardian and the ElectionGuard administrator will be assigned their own Surface Go tablet to run the ceremonies and will use Windows Hello to authenticate on their assigned device.
 
@@ -26,7 +26,7 @@ As a result,there are known aspects of the full 2.0 specification that will not
 
 There are fixes already in place that will be published after College Park, but to meet deployment and QA timelines were not released as part of 1.91.18. While it is not best practice by any means to intentionally omit support of components of independent verifier validations, some validations are more important than others, and the implementation risk of missing our deadlines for College Park outweighed the incremental benefit of delivery of the missing elements.
 
-In addition, there are features that are [outlined in the 2.0 spec](/spec/#v20) that are not used in the College Park election, and independent verifier support is thus not necessary nor expected for 1.91.18:
+In addition, there are features that are [outlined in the 2.0 spec][election-guard-spec-v2_0] that are not used in the College Park election, and independent verifier support is thus not necessary nor expected for 1.91.18:
 
 * Ballot chaining
 * Pre-encrypted ballots
@@ -36,7 +36,7 @@ In addition, there are features that are [outlined in the 2.0 spec](/spec/#v20)
 
 Finally, when the verifier was run initially immediately after the tally ceremony on November 5, a data error was discovered around the extended base hash, causing the MITRE 1.I verification (1.H in the 2.0 Specification) to fail. The error was due to an already-addressed issue regarding equation formulation, yet the desired approach was implemented differently in the verifier versus the production code. Since the core ElectionGuard code could not be updated (due to the code freeze cited above), the verifier was modified to interpret the extended base hash correctly and the election was fully verified according to the precepts agreed to above.
 
-!!! abstract "The [MITRE Requirements document](/images/MITRE-EG-CP-requirements.pdf) outlines in detail the encryption and election record capabilities adopted by their verifier for College Park."
+!!! abstract "The [MITRE Requirements document][mitre-requirements-doc] outlines in detail the encryption and election record capabilities adopted by their verifier for College Park."
 
 !!! tip "Run the verifier yourself!"
     If you want to run the MITRE verifier yourself, [follow the instructions here](https://mitre.github.io/ElectionGuardVerifier1X.jl/index.html). The [election record for College Park is available at the confirmation code lookup website](https://app.enhancedvoting.com/results/public/cc/CollegePark/nov23).
@@ -47,5 +47,8 @@ Finally, when the verifier was run initially immediately after the tally ceremon
 In-person voters will be asked to participate in an exit survey, and all College Park residents are welcome to participate in an election survey collecting general election feedback in addition to perspectives on ElectionGuard. Upon survey completion, the Center for Civic Design will publish a report on voter sentiment.
 
 <!-- Links -->
-[College-Park-Banner]: /images/ElectionGuard_College_Park_2023.svg "College Park Banner"
-[hart-scanner]: /images/votingmachine.jpeg
+[election-guard-spec-v2_0]: ../spec/index.md#v20
+[College-Park-Banner]: ../images/ElectionGuard_College_Park_2023.svg "College Park Banner"
+[preston-idaho-pilot]: Preston_Idaho_2022.md
+[hart-scanner]: ../images/votingmachine.jpeg
+[mitre-requirements-doc]: ../images/MITRE-EG-CP-requirements.pdf
diff --git a/docs/elections/Fulton_Wisconsin_2020.md b/docs/elections/Fulton_Wisconsin_2020.md
@@ -14,4 +14,4 @@ Three election guardians oversaw the ElectionGuard tally process. No independent
 ### ["Microsoft’s voting software is getting its first test in a small Wisconsin town" CNBC, February 18, 2020](https://www.cnbc.com/2020/02/18/microsoft-electionguard-software-gets-first-test-in-fulton-wisconsin.html)
 
 <!-- Links -->
-[Fulton-Banner]: /images/ElectionGuard_Fulton_2020.svg "Fulton Banner"
+[Fulton-Banner]: ../images/ElectionGuard_Fulton_2020.svg "Fulton Banner"
diff --git a/docs/elections/Preston_Idaho_2022.md b/docs/elections/Preston_Idaho_2022.md
@@ -45,6 +45,6 @@ MITRE wrote an independent verifier for this election to ensure that ElectionGua
      * Increased their confidence in the accuracy and security of elections. 
 
 <!-- Links -->
-[Idaho-Banner]: /images/ElectionGuard-Idaho-2022.svg "Idaho Banner"
-[hart-scanner]: /images/votingmachine.jpeg
-[EAC-Report]: /images/EAC%20Report%20Final.pdf
+[Idaho-Banner]: ../images/ElectionGuard-Idaho-2022.svg "Idaho Banner"
+[hart-scanner]: ../images/votingmachine.jpeg
+[EAC-Report]: ../images/EAC%20Report%20Final.pdf
diff --git a/docs/index.md b/docs/index.md
@@ -57,7 +57,7 @@ A huge thank you to those who have helped us along the way:
 [oxide-design]: https://oxidedesign.com/ "Oxide Design"
 
 [contribute-index]: contribute/index.md "Contributors"
-[glossary-end-to-end-verifiable]: overview/Glossary/#end-to-end-verifiable-elections "End-to-End Verifiable Elections"
-[glossary-post-election-audit]: overview/Glossary/#post-election-audit "Post-election audit"
+[glossary-end-to-end-verifiable]: overview/Glossary.md#end-to-end-verifiable-election "End-to-End Verifiable Elections"
+[glossary-post-election-audit]: overview/Glossary.md#post-election-audit "Post-election audit"
 [develop-getting-started]: develop/Getting_Started.md "Developer - Getting Started"
 [roadmap]: overview/Roadmap.md "ElectionGuard - Roadmap"
diff --git a/docs/overview/Glossary.md b/docs/overview/Glossary.md
diff --git a/docs/overview/Roadmap.md b/docs/overview/Roadmap.md
diff --git a/docs/spec/Serialization_Spec.md b/docs/spec/Serialization_Spec.md
diff --git a/docs/spec/index.md b/docs/spec/index.md
diff --git a/docs/use_cases/Precinct_Scan.md b/docs/use_cases/Precinct_Scan.md
diff --git a/mkdocs.yml b/mkdocs.yml
