tally routine should target multiple ballots at once. this reduces communication cost by extracting all relevant votes from a user in one communication.

• milestone 1: prioritization polling based on QV and user credit balances (~1.5 month)

  • build out working prototype (1 month)
    • identity management
      • generating new identities with ed25519 signature keys
    • community user and group management
      • user operation for user management
      • group operation for group management
      • member operation for membership management
      • balance operation for balance management (badges, voting credits, etc.)
    • prioritization polling operations
      • poll operation (create a poll)
      • vote operation (vote on an open poll)
      • tally operation (collect votes and report aggregates)
      • seal operation (finalize a poll and merge into main branch with a verifiable record)
      • list operation (list open polls)
    • demo and feedback from glen
      • users can transfer balances to other users
        • generic mechanism for sending messages across repos
        • process governance operation requests arriving as messages
        • implement "transfer balance" operation
      • voting subtracts from user credit balances
    • dogfood deployment to gov4git repo (expected in November 2022)
      • github actions
      • instructions "how to vote on issues and PRs"

• milestone 2: verifiable merge approval (1 month)

  • TBD

• milestone 3: community history verification (1 month)

  • TBD

• milestone 4: browser extension for voting on GitHub (?? month)

  • TBD

• milestone 5: pre-live polish (1 month)

  • evaluation of user experience
    • installation flow
    • error messages and corrective suggestions
    • issue tracking setup and bug reporting automation
  • versioning and interoperability
    • add governance protocol version info in git artifacts
  • documentation
    • blog article describing end-to-end user workflow and effect of operations on git repos
    • terminal screencast video demonstrating user workflow
  • test
    • testing framework
    • test coverage (all operations)
    • setup pl github management

Upon various dynamic events (such as when PRs are accepted), community members may receive voting credit payouts.
Ideally, we have a mechanism for the community to notify members of changes to their accounts.
We can accomplish this by implementing member mailboxes, which members can view in the desktop app.

Your public repo

https://github.com/tflaj/gov4git.public

Your public branch

main

Your email (optional)

[email protected]

We need to understand all mechanisms (features) that Glen plans to add to the application (on top of the features from #31) for the public launch. These will be the last product features going into the public launch.

Let's collect the requirements and record them here.

I am pasting from emails what input we have from Glen so far:

1. Over the course of a week, the maintainer adds and removes credits from various accounts.
2. An issue is posted. Over the course of the week, various contributors add and subtract votes from it. These translate into a priority score according to quadratic funding. The current funding level is continuously pushed to the client to allow it to be viewed and ordered by priority. Then, at some point, someone submits a PR to address the issue. At this point, the current priority on the issue freezes, contributors can no longer adjust their contributions to this issue.
3. Continuing the scenario from 2, a PR poll now opens. Over the course of a week, contributors adjust their votes (via QV) on whether the PR should be approved, ahead of a deadline at the end of the week. As they do so, they also submit a number of credits they want to “bet” up to the amount of votes they have on this issue, that it goes their way. At expiry, the users are paid out 2 to 1 on the amount bet if the choice went their way; all credits committed to voting are collected and burned.
4. In the case that 3 ends in the PR being rejected, we return to stage 2 and the QF exercise unfreezes .
5. In the case that 3 ends in the PR being accepted, the person submitting the PR gets credits equal to the priority.

Questions:

• What if PRs only address an issue partially?

Let $v_u^t$ be the voting credits user $u$ applies to a ballot choice at time $t$. Here $v_u^t$ can positive or negative.

The tally score of the ballot choice equals:
$$\sum_u \sqrt{\sum_t v_u^t}$$

The credits spent by an individual user $u$ equal:
$$\left| \sum_t v_u^t \right|$$

Write a whitepaper covering:

• problem statement of open-source community governance
• analysis of existing approaches (smart contracts, daos)
• solution approach
  • governance is a decentralized social application with a chain-like state
  • architecture for building social apps on top of git
  • architecture for embedding a chain inside git
• comparison with other architectures for decentralized social apps (inrrupt, bluesky, scuttlebug)
• trust model
• other applications (messaging over git, indexing/DHT over git)

Labels such as gov4git:join, gov4git:prioritize, gov4git:directive must be created in the project repo before they can be used. This should be done automatically by the deployment automation.

add functionality: given the user's github credentials, provision a public and private repos for the user and initialize them with a new identity

Describe the bug

Running gov4git ballot show --name issues/1 returns file does not exist. I can confirm that the ballot exists with gov4git ballot list. This command worked on previous versions of the CLI but is failing on 1.1.4. I tried updating the cache and it still fails. Running this on Windows.

Describe the bug
I updated to the newest cli, version 1.1.4, and added the follow values to ~/.gov4git/config.json

  "cache_dir": "/Users/derek/.gov4git/cache",
  "cache_ttl_seconds": 120,

I am working with an existing community and identity repos so I skipped the init commands. The first command I ran after updating was gov4git ballot show --name issues/1 which resulted in the following error

 g4g ballot show --name issues/1

url="\\Users\\derek\\.gov4git\\cache\\ufxiq2z37alq4jvk52ra5xmw5d74t4ql5ine72rzz43gsn4vg44a\\repo" refspecs=["refs/heads/main:refs/heads/main"] err=exec: "C:\\Program Files\\Git\\mingw64\\libexec\\git-core\\git-upload-pack": file does not exist

I tried running gov4git cache update, which results in no response in the CLI, then rerun the above command and I get the same error. I also get the error from other commands such as gov4git ballot list.

The command appears to create the cache directory filled with guid directories but seems to fail to locate the git-upload-pack. Why is it searching for git binaries? I thought a pure go implementation of git was being used. Any suggestions?

I am running this on Windows.

Introduce an "automation mode" for the cli, whereby the client interprets the standard-in as a JSON-encoded command invocation with arguments, and returns the result to standard-out also JSON-encoded.

@dworthen Later on as the API surface expands, using something like this may be more convenient than fiddling with command-line flags. WDYT?

Your public repo

https://github.com/govi218/gov4git.public

Your public branch

main

Your email (optional)

[email protected]

The desktop app should:

• terminate any background gov4git update --seconds 120 process
• call gov4git cache clear
• restart gov4git update --seconds 120 in the background

Your public repo

https://tasadar.net/tionis/gov4git.public

Your public branch

main

Your email (optional)

[email protected]

When the app needs to collect communications from the community users, it clones the contents of their repositories. This is currently done sequentially, which can become slow if the number of community members is large. The remedy: perform multiple clones concurrently with a throttle.

Your public repo

https://github.com/the-kscar/Gov4gitTest_Public

Your public branch

main

Your email (optional)

[email protected]

Your public repo

https://github.com/shaudubey/gov4git.public

Your public branch

main

Your email (optional)

[email protected]

• #31
• #35
• #44

problem and high-level solution

currently UI operations that require reading from the community will experience a small latency, caused by fetching the difference between the community repo and the local cache.

it is possible to remove this latency entirely.

the key idea is to fetch the community repo to the local cache pro-actively at regular intervals (such as every 3 minutes).
when the gov4git client needs to read the community repo, it will not attempt to fetch it unless the cache is stale (older than 3 minutes).

the user will see 3 minute old community data, which should not be a problem considering that community updates (vote collections) will happen on an approximately hourly basis.

the cli will have a dedicated command cache update to accomplish the local cache refresh. however, since the cli is not a long-lived process, the cache updates must be driven by the desktop app. this could be accomplished in one of two ways:

• either the desktop app maintains an internal loop on a separate thread that calls gov4git cache update every few minutes,
• or the desktop app can start a background copy of gov4git, whose only task is to perform regular cache updates, which could be placed behind a command like cache update --minutes 3

technical details

• verify that file locking works both on Mac and Windows (to prevent concurrent cache access from racing)
• spin-like lock over lock files to prevent races between cli instances (provided by flock library)
• include an optional TTL for cached repos in the config file

Write up a formal, user-friendly, model of the management mechanism

The desktop app should run gov4git cache update --seconds 120 in the background (see #65), while the app is running.

Milestone 1 includes a baseline set of application features, as well as operational preparedness of the software stack for live deployment to an internal group of users. The product spec for milestone 1 can be found here https://github.com/gov4git/gov4git/blob/main/doc/product-spec-m1.md

Technical roadmap

Technical tasks for this milestone:

Backend (command line client) features

• #33
• #51
• #52
• #59
• support for cancelling ballots
• #54
• #56
• #57
• #58
• #65 (enables zero-latency UX)

Integration with desktop (the desktop app)

Operational readiness

• #50
• #41
• desktop app logs the verbose cli output for troubleshooting purposes
• #42

Features

• #68
• #67

Integration with GitHub

• cli command for importing GitHub issues and request
• GitHub action template for importing from GitHub and sweeping the community votes
• deployment instructions

Frontend Desktop App

• decide and freeze terms for "voting credits" vs "impact" (after the square root)
• UI user stories: gov4git/desktop-application#55
• screen for tracking user's past votes (with details) and which have been processed?

Tests

Backend tests

Application correctness tests:

• #45
• #47
• test open ballot, vote, tally, close ballot
• test freeze/unfreeze ballot
• test transfer credits from one account to another

Command-line client interface tests. These tests ensure that the command-line interface (which is used by the desktop app) behaves as expected. These tests also act as a specification of the cli interface.

• #49
  • test interface of balance command
  • test interface of ballot command
  • test interface of group command
  • test interface of user command
  • test interface of member command
  • test interface of init-gov command
  • test interface of init-id command

Integration with desktop tests:

• manually test all UI features and flows (installation, creating identity, etc)
• manually verify desktop app does not freeze while communicating with backend

Integration with GitHub tests:

• test that each GitHub action invokes the cli correctly (Trigger GitHub Action locally. Use cli to check for expected result.)

Business roadmap

• project website on GitHub pages
• project blog on GitHub pages (to post articles on features, collaborations, etc)

When password-protected SSH PEM files are used for authentication (in the config file), users should be queried for the respective passwords once (for each relevant repo) before operation execution begins.

Note that during an operation, a repo may be accessed multiple times so it is impractical to query the user every time a repo is authenticated into. Thus we would like query the user for passwords and cache them for the duration of the operation.

Running gov4git ballot show-open --name NAME appears to be printing out a Go struct instead of JSON.

Can we update the command to return JSON to better support the Desktop client?

All tasks here are planning for after the MVP launch.

• rehearse/optimize the lifecycle of a user filing an issue:
  • user clicks on "file an issue" button, lands on the github page for new issue with logs pre-attached and issue labeled as user-support
  • we triage it according to some simple agreed-upon routing method and labeling system
• create a user support channel on a system like zulip (threaded messaging)
  • (Discord may not be appropriate. It has a more real-time nature and users cannot find answers to past questions easily.)
• plan time for addressing user issues
• plan time for supporting glen while running the community, with tasks such as
  • batch operations
  • importing from excel
  • extracting software and mechanism metrics to watch and understand project health and dynamics
• automate archival/rollup of governance history
• track pub keys of other repos (defined by URL) in your own repo and flag changes

Your public repo

https://github.com/melscoop/gov4git.public

Your public branch

main

Your email (optional)

[email protected]

Describe the bug
When I run gov4git init-id, I receive the following error bcrypt_pbkdf: empty password

What is the expected output to verify success?

To Reproduce
As instructed the following config file was used -

{
     "auth" : {
          "[email protected]:petar/gov4git.public.git": {
               "ssh_private_keys_file": "/Users/my_username/.ssh/id_rsa"
          },
          "[email protected]:petar/gov4git.private.git": {
               "ssh_private_keys_file": "/Users/my_username/.ssh/id_rsa"
          }
     },
     "gov_public_url": "https://github.com/gov4git/governance.git",
	"gov_public_branch": "main",
	"member_public_url": "[email protected]:my_username/gov4git.public.git",
	"member_public_branch": "main",
	"member_private_url": "[email protected]:my_username/gov4git.private.git",
	"member_private_branch": "main"
}

This file is located in ~/.gov4git/config.json

I also double checked the projects were writable.

Expected behavior
A key generation file stored in the public and private repos identified.

Attach the logs
No logs available.

Could we have the config path be derived from an Env variable also ?

For example:

export GOV4GIT_DATA_PATH=$(PWD)/.data/gov4git

It will make automation also easier.

The fall through priority could bethat a ENV is looked for, and if its nil, then the -- config flag is looked for, and then the default XDG one is used. If a user provides both ENV and FLAG, then the ENV wins.

Implement the collaboration mechanisms defined in #38

• #37

Milestone 2 adds Plural Management Mechanisms to the application.

Backend

• #38
• #39

Aspirational (last priority)

• (aspirational, P1) #63

Frontend

• address all issued filed during M1 deployment (tagged with an M2 milestone on GitHub)
• incorporate management mechanisms in desktop app

Aspirational (last priority)

• (aspirational, P1) UI for member mailboxes

Testing

• setup to test cross-platform scenarios (e.g. Windows->GitHub->Mac)
• setup to verify backwards compatibility of new releases

Describe the bug

I am able to open new ballots as a community maintainer but I am unable to vote. Voting results in a "credentials are not valid" error.

g4g ballot vote --name issues/1 --choices Prioritize --strengths 4

credentials are not valid

I am using the same access_token and config files that worked with previous CLI versions and the access_token has not expired. I generated a new GH PAT just in case the old one was expired but that did not work. This started occurring after I updated to the v1.1.4 release on Windows.

Problem

Presently every invocation of the command line client fetches fresh copies of remote repos. This can become slow as repos grow in size.

Solution

The client can keep a local, on-disk cache of remote repositories and fetch only the difference.

Describe the bug

Tracking ballots returns "file does not exist" for ballots that exist but have no votes.

g4g ballot track --name issues/1

file does not exist

"file an issue" button automatically opens a github issue screen with the logs and system info attached,
allowing the user to just enter the description of their problem and submit the issue.
this would streamline processing user troubleshooting requests.

tallying requires cloning all user's public repos. as the community grows in the thousands, cloning must be done in parallel to reduce the time to perform a governance sync.

Hi all,

I have a few thoughts to help kick off the discussion on designing the desktop app's UX.

So far Glen's requirement for functionality has been to be able to designate a subset of GitHub issues to be included in a prioritization poll. In particular, this designation is dynamic: New issues can be added to a poll at any time.

Furthermore, the requirement implicitly has been to have a single "global" poll. I think it is safe and wise to generalize this slightly and allow any number of named prioritization polls, such that an issue can be added to any number of named polls. (What do you think?)

So hereafter I'll use the term "poll" to mean a named subset of GitHub issues.

There are two UX questions regarding polls, corresponding to the admin and member roles:
(1) How does a project administrator add a GitHub issue to a poll
(2) How does a project member view polls and their issues, and cast votes

I think (1) has a natural design. Applying a specially formatted GitHub label to an issue can trigger adding the issue to a poll. For instance, applying the label "in_poll:name_of_poll" would add the issue to a poll called "name_of_poll". This flow does not pertain to the desktop app. We would simply use a GitHub action that is triggered when labels are applied to issues. The action would directly invoke the gov4git client to create the poll (if necessary) and add the issue to it.

Question (2) naturally pertains to the desktop app. Here it appears that the desktop UX design needs to assist the user to:
(a) List polls within a project
(b) For a given poll, view list of issues in the poll and the current tally (in descending order of votes)
(c) Cast voting credits to an issue in the context of a poll (an issue could be part of multiple polls)

I suppose that it will also be fairly common for a user to find an issue through the GitHub UI and want to transition to the voting interface for it. To accommodate this, pasting the issue's URL in the desktop app could lead to the issue's voting screen in the desktop UI.

Aside from these poll/issue UX flows, the only other UX consideration (for the MVP) is initializing the user's identity, which seems straightforward.

I don't want to prescribe any specific UI design, I would just mention how I think of it abstractly.
There seems to be a case for three "screens" in the UI:

a project screen, corresponding to (a) and to the GitHub repo URL
a poll screen, corresponding to (b)
an issue screen, corresponding to (c) and to the GitHub issue URL

Let me know what you think.

Running gov4git balance add --user dworthen --key voting_credits ... on Linux creates a file with a key balance/voting_credits while running the same command on Windows creates a file with a key of balance\\voting_credits.

Examples:

• File created when running on Linux: https://github.com/dworthen/g4g-demo-community-public/blob/main/members/users/se46kkxnb57mknhecuukfkslym5bfhu3dtpbzkiy4x6njyxhuuwa/wzpkjxmc3kqlff2wc3aobltsawyj24a2g5uctubtiid4afwitw5q/key.json
• File created when running on Windows: https://github.com/dworthen/g4g-demo-community-public/blob/main/members/users/se46kkxnb57mknhecuukfkslym5bfhu3dtpbzkiy4x6njyxhuuwa/fpmfzoulxmazmwr3sb4wd4b2qscdaovfavgmwz26zdwopdon3l5q/key.json