[Phase 3] HIP-45: PDF → Markdown

DAO
1

HIP 45: PDF → Markdown

Link to Snapshot.

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 .

Link to Snapshot.

1 Like
2

This Phase-3 needs to be definitve on the way the implementation should be done.
The HIP asks to make the Policy Markdown and store it “somewhere” but the lack of definition of the “where” makes it incomplete.

I’d recomend to wait until HIP-51 is passed and finished, and publish this Phase-3 using the Poh Library to store the Markdown on IPFS on that Library.

If you dont want to wait, I think this Phase-3 HIP should make an definite explicit indication on the place of storage.

3

The HIP asks to make the Policy Markdown and store it “somewhere”

What do you mean? The HIP states that the Markdown is kept and modified through a repository. The HIP does not dictate any official repository for this, but recommends using the Proof of Humanity github project to host the repository.

Then, the initial Markdown file will be posted as the Policy in the MetaEvidence.

I’d recomend to wait until HIP-51 is passed and finished, and publish this Phase-3 using the Poh Library to store the Markdown on IPFS on that Library.

The precedent for “Policy storage” is that they are not stored anywhere. This was not a concern in this HIP. Technically, you can access just by checking the last MetaEvidence in the PoH contract. But, if in that HIP a process to formalize official PoH storage will be done, then, this HIP-51 should make the specification for the Policy as well.

2 Likes
4

Understood. I thought he PDF was still going to be used for Policy.
Then I have no objections!

1 Like
5

I support this.

Thoughts on how to display the policies to the end-users.

Someone previously said to derive the PDF from the markdown but it makes things a bit complicated because generating the PDF is a trusted operation. It requires trust in who/whatever is producing it. If we really want to do that, we should use Github Actions, it’s the most transparent way to do it, if someone modifies the GH Actions workflow it will be detected and auditable. But do we upload this PDF to IPFS too? How do we track which PDF CID corresponds to which markdown CID? etc. Too complicated.

Another way is to process and render the markdown dynamically in the Court frontend. It is the most straightforward, no additional file to generate/store/track. The only drawback is that if someone wants to see the raw text from .md file it won’t be pretty, although still readable.

4 Likes
6

This would still be a trusted environment rather than trustless, unless implemented on an IPFS client only UI. However I agree that the UI should be in charge of processing the markdown.

MD markup is not that illegible. It’s actually pretty human read friendly, I i’m not sure it would be a problem reading the raw file

2 Likes
7

Sure but the frontends are implicitly trusted already so it doesn’t add a new security assumption. If a frontends is not trusted, no user should interact with it as it might mislead the user in many possible ways. In practice it’s acceptable because the frontends are easily replaceable if needed (more so than a deployed smart contract at least).

1 Like
8

Could formalize it by allowing anyone to generate the PDF, upload it to any IPFS, submitting it to a curated registry (or governance if proffered) and link it up in IPNS/ENS.