The Essential Guide to Election Security

About the project

Doc explainer for those that stumble on the repo goes here

Contributing

Before contributing to the EGES, please read the style guide.

Installation

Prerequisites

The documentation is built with Sphinx. Use of pipenv is optional, but encouraged for easier requirements management, built-in virtual environments, and local testing. See the pipenv documentation for installation options.

Setup

Navigate to the project directory (assuming you're not already there) and install the required packages.

cd /path/to/Essential-Guide-to-Election-Security

Install packages using pipenv

This one line should install all the necessary requirements.

pipenv install

Install packages using pip

Using pip, you'll have to specify the requirements file that contains the list of required packages.

pip install -r requirements.txt

Build the documentation

If this is the first time you're building the documentation–or if you've made changes to any of the files–do the following:

cd docs

Build (if pipenv)

pipenv run sphinx-build -b html source build

Build (if pip)

sphinx-build -b html source build

View the documentation

After executing the above, navigate to the docs folder and run the following commands:

python -m http.server --directory build

Open a browser and connect to http://localhost:8000 and you should see the documentation.

Keeping requirements up to date

Regardless of whether you're using either pipenv or pip, there are two requirements files to be kept up to date: the Pipfile and requirements.txt. Pipenv is useful for local development, but Read the Docs will only install from requirements.txt. When you perform pipenv install <some_package>, pipenv updates the Pipfile for you. To update requirements.txt, run the following command:

pipenv run pip freeze > requirements.txt

This will overwrite the existing requirements.txt file with the newest updates.

If you add a package with pip, you'll have to edit the Pipfile with the package and version using the required syntax.

Adding a new best practices

1. Create a dedicated issue for the new bp
2. Draft and finalize bp
3. Rebase if necessary
4. Add to index.rst
5. Add to bp_index.rst with priorities for each maturity
6. Update glossary and acronyms, if necessary
7. Check whether it needs to be added to maturity priorities
8. Squash and Merge PR into a staging branch (gets rid of nit pick commits)

Publishing a new version

1. Create a dedicated branch off main, ideally named staging-202xqy or 20xqy-release. The date should be the quarter beginning when the version is released (e.g., q4 for the sep 30/oct 1 release)
2. Use issues/branches for all changes, then merge into staging branch
3. Update conf.py by incrementing version and release
4. Commit directly to staging-202xqy
5. Create and review PR for prepared staging branch into main
6. Merge commit into main (do not squash)
7. After merging, go to releases and select draft a new release
8. Title the release 202xqy release and create a tag called vx.x.x as appropriate
9. Provide a description, ideally including details of changes