[Phase 3] [Binding] HIP 45: PDF → Markdown

HIP: 45
title: Rewrite Policy in Markdown instead of PDF
author: @greenlucid
status: Phase 3
created: 2022-06-23
conflicts with: None
languages: EN

Simple Summary

Migrate the policy from PDF to Markdown, and edit the policy in a repository.

Abstract

Policies should be written and edited in Markdown. This makes coordination easier and, in particular, speeds up policy editions, even more so when dealing with concurrent HIPs. A repository will be built under Proof of Humanity GitHub for this purpose.

Motivation

Using pdf as the raw document for a policy is a coordination disaster. There is too much friction around making changes to the policy to integrate the HIPs that affect it. With a PDF, the latest working document must also be made available, which introduces delays. Also, to make this new quality of life explicit, a repository will be used to coordinate the changes.

Rationale

The format should be easy to edit, audit, and replicate. The format should make it easy to follow changes and notice mistakes, just like code repositories do. Code repositories are the state of the art solution to coordinate changes across technical files (source code), so it makes sense to also use a repository for a critical document such as the PoH registration policy.

The official Proof of Humanity GitHub was chosen as a default option, but this HIP does not mandate it must be the only repository to use. Although, it is recommended to contribute all changes in the same repository, for clarity.

Implementation

Make a repository for the express purpose of containing this policy, or other important files (such as the MetaEvidence jsons). This rewrite of the policy will be the starting basis for the repository:

poh-policy.md (feel free to make PRs to fix issues during this Phase 2) Rendered sample (this render is not particularly good)

The process to edit and champion HIPs that modify the policy should be the following:

• The champion of the HIP forks the repository containing the policy.
• The champion creates a draft Pull Request to the base repository with the name of the HIP and a link to the HIP in the description.
• The champion writes the changes to the policy, and asks for reviews and feedback. This can be done during Phase 1 or Phase 2.
• After the feedback process, the PR stops being a Draft and no further changes are allowed. The HIP then gets to Phase 3.
• If the HIP passes, the PR is merged.

When this HIP is merged, the Markdown document that was specified above, will be provided as it is, without rendering, as a plain Markdown file, on the MetaEvidence.

FAQ

Who are “the reviewers”?

This is purposely under-specified. It could just be voluntaries or enthusiasts, but there’s no explicit need for them to be authority figures, or Mission Board members. My suggestion is that a few eyes that don’t agree with the HIP should also take a look.

Isn’t this complicated for non-technical contributors?

It’s certainly not harder than what we currently have. But, if this was the case, I will write a short guide on how to join a repository and follow the steps for non-technical people to champion or contribute to HIPs.

Won’t it be ugly for the users to show a raw text file?

It is possible to use a browser extension to render markdown dynamically. This is such an example .

As a previous step to this Phase 3, a signaling vote was made to decide whether if the Policy should be published as Markdown or PDF. The voters decided to continue with the Policy being published as a Markdown file in the MetaEvidence. Some discussion of pros and cons was made on the topic. This is not final: if the Phase 3 rejects this migration, this whole process could take place again to decide if the Policy should be Markdown of a PDF render.

Where is the markdown policy kept?

It doesn’t matter if it’s published as a raw markdown or published as pdf, it should be kept in a repository in any case, to allow following the process indicated in the implementation header. As for the specific question of, in which repository, I would suggest to use the official Proof of Humanity GitHub repository .