diff --git a/README.md b/README.md index c57d574a..ae41af71 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,211 @@ +## How to run hbs2-peer + +hbs2-peer run [-c config] + +config is a path to a **directory** with hbs2-peer config. + +By default it is $HOME/.config/hbs-peer + + +## How make a pull request + +Since the goal of this project is to move away from +centralized services, pull requests should be done by +decentralized fashion. + +It may seem like there are too many steps here below, but +it's a full setup for creating a new distributed repo, +subscribing to changes and distributing your own changes. So +its a complete setup from the scratch to use distributed +repos with hbs2. You don't need them all if you have +already set it up once. + +In short: + +1. Setup the hbs2 +2. Make it listen the reflog for the repo +2. Clone the repo from hbs2 +3. Create a new keypair +4. Create a new reflog with the keypair +5. Export the repo to a new reflog +6. Add the repo as a new git remote +7. Work with git as usuall, push to the new created repo + +Each update is subscribed with the private key from the +keypair, so only the person who has the private key may +update the reflog. In fact, public key IS the reflog, +and the private key is a proof of ownership. + +Full procedure: + +1. Download, install and run hbs2 project. On this stage + of the project it is supposed that you are able to + install the project using the flake.nix. + + Right now, it will take a time, so be ready to it. + + +3. Optional*. Make hbs2-peer poll this topic: + +``` +echo poll reflog 1 "2YNGdnDBnciF1Kgmx1EZTjKUp1h5pvYAjrHoApbArpeX" >> +``` + + is typically +~/.config/hbs2-peer/config but it may vary up to setup + +4. Fetch the *reflog* (topic) for the repo: + +``` +hbs2-peer reflog fetch 2YNGdnDBnciF1Kgmx1EZTjKUp1h5pvYAjrHoApbArpeX +``` + +If you have the set up as in step 3, it will be done +periodically and upon hbs2-peer start, so you don't have +to bother. Also, hbs2-peer after step 3 will listen the +reflog, so new pushes will be delivered automatically. + +5. Check the reflog is here: + +``` +hbs2-peer reflog get 2YNGdnDBnciF1Kgmx1EZTjKUp1h5pvYAjrHoApbArpeX +``` + +Note, that it may take time to all objects to deliver. + +6. Clone the project + +``` +git clone hbs2://2YNGdnDBnciF1Kgmx1EZTjKUp1h5pvYAjrHoApbArpeX hbs2 +``` + +7. Create your own topic + +``` +hbs2 keyring-new > my-keyring.key +hbs2 keyring-list my-keyring.key + +[user@host:~]$ hbs2 keyring-list my-keyring.key +sign-key: 6CMRnptW8DjiW4S1kv3U6wEAUGwhZmG7522fsqi3SH2d + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +this is your new repo's relog (topic) +Of course, sign-key will be different. + +``` +Keep the keyring file private. It contains the key pair +(private+public keys) that wilyl allow you to write to the +reflog. If you lose it, you will lose the write access +to your repo. It's not a big deal, creating keypairs is +cheap. But you will need to tell anyone update theirs +references to a new repo. + +8. Export the repo to the new reflog (topic). + +``` +git hbs2 export -k +``` + +In this example, sign-key will be 6CMRnptW8DjiW4S1kv3U6wEAUGwhZmG7522fsqi3SH2d + will be my-keyring.key + +This step will export all objects to the new created +topic. + +It will take time. hbs2-git will copy all objects from +the repository to a new reflog. Although it wan't create +objects that are already in the hbs2, it takes time to +calculate hashes and check it out. So be prepared to wait +quite a while, but only for the first time. + +7. Locate the configuration file and add the keyring + +Example: + +``` +[user@host:~]$ cat ~/.config/hbs2-git/w/hbs2/config + +branch "master" + +keyring "/home/user/secrets-dir/my-keyring.key" + +``` + +Note, that keyring file must be absolute. And +the location supposed to be safe. + +In my case, it's a mounted encrypted directory, but it's +up to you. + +8. Add the new repo to a git + +``` +git remote add mytopic hbs2:// +``` + +Example: + +``` +git remote add mytopic hbs2://6CMRnptW8DjiW4S1kv3U6wEAUGwhZmG7522fsqi3SH2d + +``` + +``` +git fetch origin +git fetch mytopic +``` + +You may want to have your's topic as an origing, and other +topic as something else. It's all up to you. + + +9. Make your changes + +10. Commit + +11. Describe your changes somewhere, using PR: prefix + +See .fixme/config file to get an idea what files are +scanned for issues/pull requests/etc. + +PR is a just a fixme entry (look for fixme description) +which describes the pull requests. It just a text with +textual references to a branch, commit and other +information required for merging the changes. + + +Example: + +docs/.../some-pr-file + +``` +PR: my-very-first-pr + Just to test the concept. It may be merged from the + branch + + branch: pr-XXX-my-very-first + commit: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + +``` + +12. Commit + +13. Push + +``` +git push mytopic +``` + +Now, if the author of the original topic (reflog, repo) is +aware abour your topic and subscribed to if (added it as a +remote to his/her git repo) they will be able to receive +and merge your pull requests. + +14. Check the reflog (just for in case) + +``` +hbs2-peer reflog get +``` ## How to launch a peer