diff --git a/README.md b/README.md index 1118fa7c..36ad98db 100644 --- a/README.md +++ b/README.md @@ -75,12 +75,15 @@ Submit stories or requests to: `freddy@privacyguides.org` ## Developing +Committing to this repository requires [signing your commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) (`git config commit.gpgsign true`) unless you are making edits via the GitHub.com text editor interface. As of August 2022 the preferred signing method is [SSH commit signatures](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#ssh-commit-signature-verification), but GPG signing is also acceptable. You should add your signing key to your GitHub profile. + This website uses [`mkdocs-material-insiders`](https://squidfunk.github.io/mkdocs-material/insiders/) which offers additional functionality over the open-source `mkdocs-material` project. For obvious reasons we cannot distribute access to the insiders repository. You can install the website locally with the open-source version of `mkdocs-material`: -1. Clone this repository: - - `git clone https://github.com/privacyguides/privacyguides.org.git` +1. Clone this repository: + - `git clone https://github.com/privacyguides/privacyguides.org.git` (then `cd privacyguides.org`) - `git submodule init` - `git submodule update docs/assets/brand` + - `git config gpg.ssh.allowedSignersFile .allowed_signers` 2. Install [Python 3.6+](https://www.python.org/downloads/) 3. Install [dependencies](/Pipfile): `pip install mkdocs mkdocs-material mkdocs-static-i18n typing-extensions` 4. Serve the site locally: `mkdocs serve` @@ -91,14 +94,17 @@ This website uses [`mkdocs-material-insiders`](https://squidfunk.github.io/mkdoc **Team members** should clone the repository with `mkdocs-material-insiders` directly. This method is identical to production: 1. Clone this repository and submodules: `git clone --recurse-submodules https://github.com/privacyguides/privacyguides.org.git` -2. Install Python **3.7** -3. Install **pipenv**: `pip install pipenv` -4. Install dependencies: `pipenv install --dev` -5. Serve the site locally: `pipenv run mkdocs serve --config-file mkdocs.production.yml` +2. Enable SSH commit verification with our local [`.allowed_signers`](/.allowed_signers) file: `git config gpg.ssh.allowedSignersFile .allowed_signers` +3. Install Python **3.7** +4. Install **pipenv**: `pip install pipenv` +5. Install dependencies: `pipenv install --dev` +6. Serve the site locally: `pipenv run mkdocs serve --config-file mkdocs.production.yml` - The site will be available at `http://localhost:8000` - You can build the site locally with `pipenv run mkdocs build` - This version of the site should be identical to the live, production version +If you commit to `main` with commits signed with your SSH key, you should add your SSH key to [`.allowed_signers`](/.allowed_signers) in this repo. + ## Releasing 1. Create a new tag: `git tag -s v2.X.X -m 'Some message'`