diff --git a/AGENTS.md b/AGENTS.md index 778ffe0..68f883f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,4 +86,3 @@ hosting: njalla VPS / proxy: nginx / process: systemd / forge: radicle / funding 2. check tone: would this copy sound corporate or activist? wrong register. 3. check values: does this feature serve attention extraction? if yes, refuse it. 4. don't invent answers to open questions. flag them instead. -5. if stuck or out of depth: run `/escalate` → writes `~/.claude/handover.md` → exits. diff --git a/RADICLE.md b/RADICLE.md new file mode 100644 index 0000000..3ba328d --- /dev/null +++ b/RADICLE.md @@ -0,0 +1,197 @@ +#### (｡•̀ᴗ-)✧ *NOTE: open preview to the side in your code editor to view this doc formatted nicely* + +### **BIG!** (ﾉ◕ヮ◕) url for the radicle repo: https://radicle.network/nodes/iris.radicle.network/rad%3Az3pNdxS2udZaPJjFvAMNA6sxEVvVi + +# radicle — getting started (team member edition) + +radicle is a decentralized alternative to github. instead of pushing your code to github's servers, you push to your **local node**, which then syncs peer-to-peer with your teammates. no central server, no single point of failure. + +--- + +## wait — same folder as github? + +yes. you'll be working in the **same local repo directory** you already use. radicle doesn't replace your existing github setup — it adds a second destination called `rad` alongside your existing `origin` (github). + +think of it like having two remotes: + +``` +origin → github's servers (the old way) +rad → your local node (the radicle way) +``` + +when you push or pull, you need to be explicit about which one you're talking to — otherwise git won't know. more on this below. + +--- + +## install + +in your terminal, paste: + +```bash +curl -sSLf https://radicle.dev/install | sh +``` + +downloads and installs the radicle CLI + node binaries into `~/.radicle/bin` and updates your PATH automatically. + +--- + +## create your identity + +```bash +rad auth +``` + +generates a cryptographic keypair that identifies you on the network. think of it as your github username — but instead of an account on a server, it's a key that only you hold. you'll set an alias and an optional passphrase to protect it. + +```bash +rad self +``` + +shows your DID (decentralized identifier) — your unique identity on the radicle network. share this with your team so they know it's you. + +--- + +## get the repo + +instead of cloning with a github URL, you clone using the repo's RID (repository ID) — a stable identifier that doesn't depend on any server, like a github URL but owned by no one: + +```bash +rad clone rad:3Az3pNdxS2udZaPJjFvAMNA6sxEVvVi +``` + +this sets up a `rad` remote automatically in that repo directory. you can verify with: + +```bash +git remote -v +# rad rad://3Az3pNdxS2udZaPJjFvAMNA6sxEVvVi/... (fetch) +# rad rad://3Az3pNdxS2udZaPJjFvAMNA6sxEVvVi/... (push) +``` + +> 💡 not sure what remotes, branches, or patches are? scroll down to **"how code collaboration works in radicle"** for a plain english explainer. + +--- + +## pushing & pulling — always be explicit + +this is the most important thing to get right. because you have two remotes (`origin` for github, `rad` for radicle), always specify which one you mean: + +```bash +git push origin main # → github, as usual +git push rad main # → radicle network + +git pull origin main # ← from github +git pull rad main # ← from radicle +``` + +never just `git push` or `git pull` without specifying — git will guess, and it'll probably guess wrong. + +during the transition period, push to both when you want your changes in both places: + +```bash +git push origin main && git push rad main +``` + +--- + +## daily workflow + +```bash +git checkout -b my-feature # create a branch for your changes +# ... do your work ... +git add . +git commit -m "did a thing" # save a snapshot +git push rad main # push to radicle +``` + +local git work — branching, committing, writing issues and patches — all works offline. + +--- + +## syncing with the network + +your node only needs to be running when you want to sync with teammates. start it before pushing or pulling: + +```bash +rad node start # connect to the network and sync with peers +git pull rad main # pull latest changes from radicle +git push rad main # push your branch so teammates can see it +``` + +you don't need it running constantly — only when you want to push, pull, or sync patches and issues. + +--- + +## open a patch (radicle's version of a PR) + +once your branch is ready, open a patch with a special git push — this tells radicle to create a patch rather than just push a branch: + +```bash +git push rad HEAD:refs/patches +``` + +this opens your editor (same as writing a git commit message) — the first line becomes the patch title, the rest is the description. your maintainer and teammates will see it once their nodes sync. patches are stored as git objects so they work offline too. + +--- + +## collaboration + +```bash +rad patch list # see all open patches +rad patch checkout # check out someone's patch locally to review it +rad issue list # see open issues +rad issue open # create a new issue +``` + +issues and patches are both local-first — you can read and write them without an internet connection, and they'll sync when you're back online. + +--- + +## how code collaboration works in radicle + +### commits & branches + +a **commit** is a saved snapshot of your code at a point in time. a **branch** is a line of commits — a separate workspace where you can make changes without touching the main codebase. + +it's highly recommended to work on a branch for bigger tasks, never directly on `main`: + +```bash +git checkout -b my-feature # create and switch to a new branch +# ... make changes ... +git add . +git commit -m "did a thing" # save a snapshot +``` + +--- + +### remotes + +a **remote** is just a pointer to where your code lives outside your local machine. you probably already know `origin` — that's github. radicle adds a second remote called `rad`, which points to your local node instead of a server. + +```bash +git push origin main # → github +git push rad main # → radicle (your node, syncs to the network) +git pull origin main # ← from github +git pull rad main # ← from radicle +``` + +always be explicit. never rely on git's default remote while you're running both. + +--- + +### patches (radicle's version of pull requests) + +a **pull request** (or PR) on github is a way of saying "i've made changes on my branch — please review and merge them into main." radicle calls these **patches**. + +unlike github PRs which live on github's servers, patches are stored as git objects — they live inside the repo itself, work offline, and don't depend on any server to exist. + +once you've pushed your branch, open a patch with: + +```bash +git push rad HEAD:refs/patches +``` + +this opens your editor — first line is the patch title, the rest is the description. your teammates can check it out locally to review, and the maintainer merges it when it's ready. + +--- + +**stuck?** jump into the radicle [zulip chat](https://radicle.zulipchat.com/) `#support` channel. \ No newline at end of file