search

cosmos / governance

Resources for Cosmos governance
Creative Commons Zero v1.0 Universal
40 stars 25 forks source link

Update best practices to use markdown instead of/in addition to PDFs #1

Closed ebuchman closed 3 years ago

ebuchman commented 4 years ago

Current practice is to draft proposals in private, paste them into the forums, and then post them as PDFs to IPFS.

There's many ways we could improve on this. One would be to draft proposals as markdown files on github, for instance in this repo or a fork. Markdown files can still be compiled easily to PDF (eg. with pandoc) and posted to IPFS, but we can also just post markdown files directly to IPFS! They can also be viewed easily on IPFS through their markdown viewer, for instance I posted the best_practices.md doc to ipfs, with CID QmbkQNtCAdR1CNbFE8ujub2jcpwUcmSRpSCg8gVWrTHSWD. You can view the rendered markdown at: https://ipfs.io/ipfs/QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/example#/ipfs/QmbkQNtCAdR1CNbFE8ujub2jcpwUcmSRpSCg8gVWrTHSWD

Ultimately would be great if we could leverage Github as canonical reference, though unfortunately it's not censorship resistant. One issue with current Cosmos Hub governance is there's no way to modify a proposal once it's launched. While in theory this is a good thing, in practice it makes the system cumbersome. This is especially true for text proposals, which are technically non binding as they don't cause direct changes, so it may be valuable in certain cases to evolve them and have governance effectively commit to delegate the final form of a proposal to some small group of reviewers/committers.

Anyways, such processes are left for future experiments, but for now we should at least promote posting markdown to IPFS over PDF ! Or at least offer both :)

ebuchman commented 4 years ago

I guess one challenge with posting markdown files might be embedding images. Either you need to upload a small directly, or link to the images, or still just convert to PDF.

What's the best thing to do here? Should we recommend for now that the markdown is compiled to PDF and posted to IPFS, but that the on-chain proposal also link to the github repo and commit hash, so folks can read it there? If it disappears on github, they can always fall back to lame PDFs on IPFS ...

alexanderbez commented 4 years ago

Images should be OK if they're linked to sites and not locally referenced. I like the idea of posting markdown directly to IPFS and using that hash as point of reference in a gov proposal (assuming the hash changes if the content changes).

hxrts commented 4 years ago

Snapshot, created by the Balancer team for off-chain voting, is very simple and easy to use. I could even see forking to support on-chain transactions and the particulars of Cosmos governance.

glandua commented 4 years ago

I'd like to see improved signalling systems in the co-creative process of proposal generation. Threaded discussions and markdown instead of PDF is a good start. Having polls that note both engagement and preference is also useful (testing ideas and components of ideas). I take some inspiration from the non-blockchain project www.loomio.org (https://github.com/loomio) which is open source and perhaps could plug in to the hub or other blockchains for some sort of on-off chain hybrid for threaded conversations, signally, a final vote about specific software upgrades (or fund dispersal). Just a vision here. I really like the simple step of a substantial portion of the process of a governance proposal taking place on github, but I'd also recommend some simple tools like polling and other simple signaling tools.

ebuchman commented 4 years ago

Seems like some minor improvements on https://github.com/apex/gh-polls could suite our needs? I'm trying it out in #7 - you can already vote there. Not sure how to see who voted what though. Also can't get it working through the bot yet I just generated the poll from https://app.gh-polls.com/ and copied the markdown in

dcwalk commented 3 years ago

The current documentation mentions the use of markdown on the IPFS viewer: https://github.com/cosmos/governance/blob/master/submitting.md, however does not promote them or explicitly discourage PDFs, maybe we can consider that meeting the initial issue described here and close, or mark as stale.

Envisioning signalling improvements to the process perhaps can be taken up in a different way? There are definitely gaps and paint points around the creative and collaborative stage of proposal building and it would be great to improve forms of signalling :)

dcwalk commented 3 years ago

Going to close out in this repo as part of merge into Gaia. Please re-ticket in https://github.com/cosmos/gaia/