# Concept ngit quick start guide

This is a concept which the developer would like to work towards. a lot of the features / commands are not available yet.

## How it Works

nostr is a decentralised communications protocol with:
 - permissionless account creation - created via a public/private key pair
 - verifiable signed messages
 - messages transported via relays rather than P2P

Code Collaboration via Nostr

 * proposals (PRs), issues and related discussion, status, etc. are sent / recieved via nostr.
 * repository state stored in nostr.
 * git server(s) still required for data storage and transport but they act as dumb relays (apart from use for CI/CD).
   maintainers can change git servers via nostr and users will automatically start using the new git server.

[insert diagram which makes git severs appear like just another nostr relay - potentially something like this:]
```
             ┌──────────┐                           
             │  Author  │
             └──/─┬─\───┘
        ,------'  │  '--------.-------.     
┌──────▼─┐   ┌────▼───┐   ┌───▼───┐  ┌─▼─────┐  ┌───────┐
│  Git   │   │  Git   │   │ Relay │  │ Relay │  │ Relay │
│ Server │   │ Server │   │       │  │       │  │       │
└────────┘   └────\───┘   └───┬───┘  └──/────┘  └─/─────┘
                   \----*-.   │   ,----/---------/     
                         ┌─▼──▼──▼─┐
                         │  User   │
                         └─────────┘              
```
\* git servers are used as dumb relays with content verified via nostr events.

## Contributor's Quick Start Guide

1. install ngit
 * download [linux windows mac] (vX.X)  add binaries $PATH
 * OR if you have cargo use `cargo install ngit`
2. find repository
   * using `ngit search` eg `ngit search amethyst`
      ```
        name        maintainer(s) starred by
      > amethyst    👥Vitor       Gigi, fiatjaf, franzap, +5 👥
        amethyst    impersonator  
      ```
   * OR using gitworkshop.dev
      * browse https://gitworkshop.dev/repos for the repository
      * explore proposals and issues
      * copy the naddr (or press the green clone button to copy the clone command)
3. clone repository
 `git clone nostr://naddr123...`
4. view open proposals
   * `ngit list` - select proposal from titles to checkout branch or apply to current branch tip
   * OR review branches starting with 'origin/prs/*' with your favourate git tool
     * eg. for git cli use `git branch -r --list origin/prs/` to list and `git switch prs/add-offline-mode[e9ra8281]` to check out
     * view and contribute to the proposal discussion on gitworkshop.dev
5. submit proposal
   * `ngit send` to send with options
   * OR `git push -u` on a branch without an exisitng upstream will submit it as a proposal without commentary if you are not a maintainer 
6. update proposal
   * `git push` from your proposal branch
7. download releases using `ngit releases amethyst`
    ```
      name        maintainer(s) starred by
    > amethyst    👥Vitor       Gigi, fiatjaf, franzap, +5 👥
      amethyst    impersonator  
    ```

    ```
    amethyst by 👥Vitor
    --------------------------------------
      release                      # files
    > v0.87.7: Revert Save button  14
      v0.87.6                      14
      v0.87.5                      14
    ...
    ```

    ```
    amethyst by Vitor
    --------------------------------------
    download v0.87.7: Revert Save button (14 files)
      all (14 files)
    > amethyst-fdroid-arm64-v8a-v0.087.7.apk
      amethyst-fdroid-armeabi-v8a-v0.087.7.apk
      amethyst-fdroid-universal-v8a-v0.087.7.apk
    ...
    ```

    ```
    downloaded to ./amethyst-fdroid-arm64-v8a-v0.087.7.apk
    checksum verified
    ```

## Maintainer's Quick Start Guide
0. for completely fresh git repositories
   1. create a new local git repository
      * `git init`
      * add an initial commit with a `README.md`
   2. setup a git server with PRs and Issues disabled
      * github guide, codeberg guide, self host (gitea/forgejo guide)

1. install ngit
   * download [linux windows mac] (vX.X)  add binaries $PATH
   * OR if you have cargo use `cargo install ngit`
2. initalize on nostr
   * run `ngit init` from git repository, which will:
   1. announce with setting such as:
      * inbox relays - where contributors should send proposals / issues
      * clone - git server(s) to fetch data from
      * settings can be updated by running `ngit init` again
   2. publish state
      * from branch / tag refs on first git server in announcement
   3. add nostr as git remote
      * `git push` will now update state on nostr and push data to all git servers listed in annonucment event
3. manage proposals
   * view and apply open proposals (see contributor guide)
   * use gitworkshop.dev to comment on or close it
   * if you applied a proposal to master or used `git merge`, the proposal status will be updated when you push those commits
4. issue releases
  [TODO]
5. update comms - direct contributors to use nostr. eg. on readme and website.