craft your forge, build your project, grow your community freely
1<!DOCTYPE html> 2<htmllang="en">
3 4<head>
5 <metacharset="utf-8">
6 <metaname="viewport"content="width=device-width, initial-scale=1">
7 <title>GitRoot</title>
8 <linkrel="icon"type="image/x-icon"href="logo.png">
9 <style>
10 :root {
11--main-bg-color: #191919;
12--second-bg-color: #444444;
13--text-color: #fff;
14--accent-color: rgb(255, 94, 0);
15 }
16 17body {
18background-color: var(--main-bg-color);
19max-width: 850px;
20margin: 0auto;
21padding: 030px;
22font-family: Seravek, 'Gill Sans Nova', Ubuntu, Calibri, 'DejaVu Sans', source-sans-pro, sans-serif;
23font-weight: normal;
24color: var(--text-color);
25 }
26 27header {
28padding: 50px0;
29text-align: center;
30 }
31 32headerimg {
33display: inline-block;
34max-width: 120px;
35 }
36 37headerdiv {
38display: inline-block;
39vertical-align: top;
40padding-left: 50px;
41text-align: left;
42 }
43 44h1, 45h2, 46h3 {
47font-family: Rockwell, 'Rockwell Nova', 'Roboto Slab', 'DejaVu Serif', 'Sitka Small', serif;
48font-weight: 600;
49 }
50 51h2 {
52padding-top: 40px;
53font-size: 1.5rem;
54 }
55 56h3 {
57padding-top: 15px;
58font-weight: normal;
59font-size: 1.2rem;
60 }
61 62 .tagline {
63font-size: 1.2rem;
64font-style: italic;
65 }
66 67 .wrapper-center {
68display: flex;
69justify-content: center;
70 }
71 72 .three-parts {
73display: grid;
74grid-template: "one two three";
75 }
76 77 .part {
78margin: 020px;
79background-color: var(--second-bg-color);
80padding: 020px;
81border-radius: 5px;
82 }
83 84 .parth3 {
85padding-bottom: 15px;
86font-weight: normal;
87font-size: 1.2rem;
88border-bottom: 1pxsolidvar(--text-color);
89margin-top: 0;
90 }
91 92 @media(max-width:600px) {
93 .three-parts {
94grid-template: none;
95 }
96 97 .part {
98margin: 20px0;
99 }
100 }
101102 .part-one {
103grid-area: "one";
104 }
105106 .part-two {
107grid-area: "two";
108 }
109110 .part-three {
111grid-area: "three";
112 }
113114 @counter-stylecircleNumber {
115system:fixed;116symbols: ① ② ③ ④ ⑤ ⑥ ⑦ ⑧ ⑨ ⑩;117suffix:" ├─";118 }
119120ul {
121list-style-type: circleNumber;
122font-size: 1.2rem;
123display: flex;
124flex-direction: column;
125justify-content: center;
126margin: 40px;
127 }
128129li {
130padding-left: 5px;
131flex: 1;
132 }
133134code {
135background-color: var(--second-bg-color);
136padding: 10px;
137margin: 20px0;
138border-radius: 5px;
139white-space: preserve-breaks;
140display: block;
141 }
142143a,144a:hover {
145color: var(--text-color);
146 }
147148a[href^='http'] {
149padding-right: 1.25em;
150 }
151152a[href^='http']::after {
153position: absolute;
154content: '☍';
155display: inline-block;
156width: 1em;
157height: 1em;
158margin-left: 0.25em;
159transform: translateY(-0.25em);
160 }
161162 .accent {
163color: var(--accent-color);
164 }
165166footer {
167margin: 50px0;
168border-top: 1pxsolidvar(--text-color);
169text-align: center;
170padding: 20px0;
171 }
172173footer>p:nth-child(1)>a[href^='http']::after {
174position: absolute;
175content: '';
176display: inline-block;
177width: 1em;
178height: 1em;
179margin-left: 0.25em;
180transform: translateY(-0.25em);
181 }
182 </style>
183</head>
184185<body>
186 <header>
187 <imgsrc="logo.svg"188alt="Logo of GitRoot, represent a big G with roots inside with traditional dot lines of git">
189 <div>
190 <h1><spanclass="accent">G</span>it<spanclass="accent">R</span>oot</h1>
191 <pclass="tagline">Forge your idea to build a product with your community.</p>
192 </div>
193 </header>
194195 <sectionclass="wrapper-center">
196 <divclass="three-parts">
197 <divclass="part part-one">
198 <h3>🔓 Liberty</h3>
199 <p>GitRoot is <spanclass="accent">FOSS</span>, you can do anything you want with it, except sell it
200 (AGPL).</p>
201 <p>Host it yourself or test it in its cloud version, your code, your data = your choice.</p>
202 </div>
203204 <divclass="part part-two">
205 <h3>⛓ Integrity</h3>
206 <p>GitRoot is a <spanclass="accent">git forge</span>, where all data is stored in git. From
207 configuration to issues, from request-pull to comments, from users to bump issues.</p>
208 <p>Yes, all is stored in a git repository. That means you can manage, organize, develop and configure
209 all
210 your community from your preferred IDE and your standard git client.
211 </p>
212 </div>
213214 <divclass="part part-three">
215 <h3>🚀 Collaboration</h3>
216 <p>GitRoot is the heart of your community. When you build a product, code is a requirement but
217 community is the next thing to have. And what better than having the <spanclass="accent">data of
218 your community</span> just aside your code.</p>
219 <p>Imagine new workflow if your forum thread can became an issue, resolved to a request-pull and finally
220 released, all of that from the same git reposity.</p>
221 </div>
222 </div>
223 </section>
224225 <section>
226 <h2>How it works</h2>
227 <p>Download and launch GitRoot:</p>
228 <code>> wget url && chmod +x gitroot && gitroot --directoryData="./data"</code>
229230 <p>From there all the next steps are done with git. The first repository created by Gitroot, named 'gitroot', is
231 now available for cloning :
232 </p>
233 <code>> git clone ssh://URL/gitroot</code>
234235 <p>Inside the GitRoot directory you can create your first repo:</p>
236 <code>> echo "myRepo" > repositories && git commit -am "add myRepo" && git push</code>
237238 <p>GitRoot has added you as the owner of this repo. Now you can activate some plugins, just like that:</p>
239 <code>> git clone ssh://URL/myRepo && cd myRepo
240> echo "issue\nrequest-pull" > .gitroot/plugin.md && commit -am "add plugins" && git push</code>
241242 <p>Then you can create an issue:</p>
243 <code>> echo "#My first issue" > issues/first.md && commit -am "add first issue" && git push</code>
244245 <p>Or you can create a request-pull by creating a simple branch, GitRoot will manage all the rest for you:</p>
246 <code>> git checkout -b myFirstRequestPull
247> echo "---\ntarget=main\n---\n#My first request-pull" > requestpull/first.md
248> commit -am "add first request-pull" && git push</code>
249250 <p><spanclass="accent">No need to fork, no need to leave your IDE</span>, just work and lets fancy things to
251 GitRoot. Imagine how easy it becomes to find issues related to topic:</p>
252 <code>> grep -r "topic" issues/</code>
253 </section>
254255 <section>
256 <h2>Why?</h2>
257 <p>GitRoot take inspiration from a lot of open-source projects, and want to gather all users of a product into a
258 git forge.</p>
259 <p><ahref="https://nixos.org">Nixos</a> is an OS where the configuration permits to build your OS. Why my forge
260 doesn't allow me to <spanclass="accent">configure my repositories with git</span> itself?</p>
261 <p>PKM (<ahref="https://obsidian.md">Obsidian</a>, <ahref="https://anytype.io">Anytype</a>... too much to cite
262 them all) are products where your data are linked and search inside them is easy. Best PKM permits to write
263 <spanclass="accent">data in md</span> (free form) and permit to be local first. Why my forge doesn't allow
264 me to build my project when the server is down? Because extra data (issues, boards, releases) are missing,
265 they are in their database, not in <spanclass="accent">my working directory</span>.
266 </p>
267 <p><ahref="#forges">Others forges</a> are products which focalise on code and where others collaborators
268 are third party players. Why my forge looks like a traditional directory explorer? Why translators loose
269 commit authoring (when using third party apps, it's a technical-user which commit for them)?</p>
270 <p><ahref="https://wordpress.com">Wordpress</a> is a project where company can build and manage their site web.
271 Why my forge doesn't allow my company to do the same? Especially if my company is doing a web product.</p>
272 </section>
273274 <section>
275 <h2>GitRoot grows with you</h2>
276 <p>At the beginning,, there is just a git server, but it can evolve into a platform where all users of your
277 product can have a role.</p>
278 <ul>
279 <li>When you have an idea, you just want to start coding: install gitroot and you are covered</li>
280 <li>When your first users come, you want to communicate with them in a simple way: install the <a281href="#plugin-issue">issue</a> plugin and let them push</li>
282 <li>When your community grows, you want to manage it: install <ahref="#plugin-ci">CI</a>, <a283href="#plugin-web">web</a> or <ahref="#plugin-water">water</a> plugin and push</li>
284 <li>When your community is established, just enjoy!</li>
285 </ul>
286 </section>
287288 <section>
289 <h2id="forges">Forges</h2>
290291 <h3>Alternatives</h3>
292 <p><ahref="https://github.com">Github</a>: not open-source, US hosted</p>
293 <p><ahref="https://bitbucket.org/">Bitbucket</a>: not open-source, US hosted</p>
294 <p><ahref="https://gitlab.com">Gitlab</a>: US hosted, way too big to host and to use. Why a forge needs 8Go ram
295 for a tiny project?</p>
296 <p><ahref="https://gitea.com">Gitea</a>/<ahref="https://forgejo.org/">Forgejo</a>: Almost perfect, FOSS,
297 hostable, small. But to manage my product, I need to go to its URL, to move from it to another forge I need
298 to have to use tricky api for all data except code.</p>
299 <p><ahref="https://gogs.io/">Gogs</a>: Almost perfect too, FOSS, hostable, small. But personalization is not
300 the main concern of it. They don't encourage to modify templates. They don't have plugins.</p>
301 <p>GitRoot: FOSS, hostable, small. Main concept is to gather <spanclass="accent">all your community</span> (and
302 data generated by them) <spanclass="accent">in your forge</span>. Not only for coders, but also
303 translators, users, <ahref="#plugin-social">marketing</a> or sales.</p>
304305 <h3>Others/Specifications</h3>
306 <p><ahref="https://radicle.xyz">Radicle</a>: Almost perfect too, they include issues in git, but not in the
307 working directory. They focus on p2p repository which is a good concern to prevent code loss, but that's not
308 the problem GitRoot intends to fix. Maybe in the future GitRoot would implement their specification to be
309 able to be a node of the network.</p>
310 <p><ahref="https://forgefed.org/">ForgeFed</a> is an interesting alternative. This forge is built with
311 fediverse to be able to federate multiple instances. GitRoot could implement it.</p>
312 <p>GitRoot: wants to be compatible with others federated/p2p forges. But wants to mostly focus on extra-data of
313 a project. Specifications in GitRoot will be about the representation of an issue, request-pull, users and
314 not so much about the protocol to replicate data. It's complementary to those tools.</p>
315 </section>
316317 <section>
318 <h2>Q&A</h2>
319320 <h3>How to log in?</h3>
321 <p>Although everything is managed by git, there is no login. When a user pushes code we only need to check the
322 author is referenced in the "users" file. Sadly, git as no way to know the author is really the author. So
323 we choose to force to <spanclass="accent">sign all commits</span>. To add a commiter to the repo (someone
324 which can change the main branch) you just need to add a line in the ".gitroot/users.md" file. Or even
325 better, let other users adding their line and make a request-pull.</p>
326327 <h3>How to fork?</h3>
328 <p>Unlike other forges, we <spanclass="accent">don't encourage fork</span> just to make a contribution. All
329 users can create a branch on your git repository. And request-pull against your main branch.</p>
330 <p>But if you want to fork a repo to a trully fork because of misalign direction, it's <spanclass="accent">just
331 git</span>:</p>
332 <code>> cd $GITROOT_CLONE && echo "myFork" > repositories && git push
333> git clone ssh://URL/myFork && cd myFork
334> git remote add upstream ssh://original && git pull upstream
335> git push
336</code>
337338 <h3>Manage multi-repos project?</h3>
339 <p>GitRoot encourages and embraces <spanclass="accent">mono-repo</span> strategy. But sometimes you can't. In
340 other forges you have a group for your platform and multiple repositories for your code. You can do the same
341 thing with GitRoot. Just create repositories with the name "myGroup" then "myGroup/myRepo1" and
342 "myGroup/myRepo2". Create your issues/doc/forum... in the "myGroup" repo.</p>
343 <p>What is cool with GitRoot is that it is really <spanclass="accent">simple to manage issues</span>. In your
344 workstation, to move an issue from root to subproject, you just need to:</p>
345 <code>> cp myGroup/issues/my_issue.md myGroup/myRepo1/issues/my_issue.md</code>
346 <p>The same is true for all your data. Maybe in the future, we will add some helpers (mostly bash) to automatize
347 moving, commit and push.</p>
348349 <h3>How to manage users?</h3>
350 <p>Every GitRoot repositories has a ".gitroot/users.md" file. In it, there are as many sections as you
351 want. For example imagine having 3 sections: owner, maintainer, contributor. Every section contains branches
352 managed by this section (optionnaly files in those branches) and users with pseudo=PGP/ssh. In the next
353 example, owner can change all files in main branch. Maintainer can change the code in the main branch except
354 for the "user" file. A contributor can manage "issues/incoming" directory. And all other diff, will need to
355 be approved by maintainer or owner depending on what is changed.</p>
356 <p>Anyone can create a branch and push code to it. When a user wants to merge his code, it needs to request-pull
357 from a user with the good rights.</p>
358 <code>
359# owner
360361## branches
362363- main
364- otherBranch
365366## users
367368- pseudo=PGP
369370# maintainer
371372## branches
373374- main::-/users.md
375- otherBranch2
376377## users
378379- pseudo2=PGP
380- pseudo3=PGP
381382# contributor
383384## branches
385386- main::/issues/incoming
387388## users
389390- pseudo4=PGP
391- pseudo5=PGP
392</code>
393 <p>When a user pushes a new branch to your git repo, GitRoot add automatically a new section, to be sure only
394 user can change its own branch, optionally it can also add the current branch to all other groups to be
395 sure maintainers can update the request-pull:</p>
396 <code>
397 # current
398399 ## branches
400401 - currentBranch
402403 ## users
404405 - currentUser=PGP
406</code>
407 <p>Of course, the file will be cleaned to be able to be merged by a maintainer.</p>
408409 <h3>Why use GitRoot if I can do the same in Git(hub/lab/tea)?</h3>
410 <p>Yes you are right, putting <spanclass="accent">all your data in git</span> is not reserved for GitRoot. It's
411 exactly for that reason that we want to build it : to demonstrate that there is another way to organize a
412 product development. And yes, <spanclass="accent">mirroring</span> your GitRoot to a Github account is
413 encouraged. In that way, not only your code but also all the data that made your idea a product will be
414 shared.</p>
415 <p>With GitRoot, issues are not only issues but can become a section of your static site Q&A. <span416class="accent">All is in your git</span> repository and all is sharable between issues, code and static
417 website.</p>
418 <p>With GitRoot metadata of your data is checked, linted and can be forced.</p>
419420 <h3>How to backup?</h3>
421 <p>All is git, really. On another machine, in another hosting or just in another forge you will be safe. What
422 about data of last year? git checkout covers you.</p>
423 <p>Simple backup management:</p>
424 <code>> ssh backup -c "git pull"</code>
425 <p>Another backup: <ahref="#plugin_mirror">mirror</a> to github</p>
426427 <h3>Where is pricing?</h3>
428 <p>For now GitRoot is <spanclass="accent">just an idea</span>. I hope it will become a project, then a
429 product. I think there will have 2 ways to sustain the project. One is a cloud version to host for you.
430 Another is to make source-available plugins and pay to use them. For example a LDAP plugin to ensure all
431 users are referenced in your system. Or plugin around business metrics that can generate income and totally
432 not be usable in FOSS organisations.</p>
433 </section>
434435 <section>
436 <h2>Challenges</h2>
437 <p>GitRoot shine when managing products extra-data. But there are zones where its unique vision can become a
438 challenge.</p>
439 <p>Realtime communication is a big no for GitRoot. How to store real time chat in git?</p>
440 <p>Big files can be a problem in git, LFS is a solution but it can be difficult to manage.</p>
441 <p>Big communities with multiple communication at the same time will not fit with GitRoot. Imagine being blocked
442 to release because user create issues too many times. Create a project just to manage forum and keep your
443 project alone can be a solution, but not pretty one.</p>
444 <p>Plugins are the leafs of GitRoot. But too many plugins can lose users. How to manage them efficienlty? What a
445 plugin can do? How plugin talk to other plugins? Those questions will require a lot of try/fail tests.</p>
446 </section>
447448 <section>
449 <h2>Plugins essentials</h2>
450451 <h3id="plugin-issue">Issues</h3>
452 <p>First there is ideas, this plugin permit to organise them. It classify, lint and fix meta-data related to
453 issues.</p>
454455 <h3id="plugin-web">Web</h3>
456 <p>All users are not coders. How my users can interact with GitRoot without knowing git? Simple, add web client
457 to your forge. This plugin will be the face of your products and also, the face of your forge. Code is,
458 probably, not the first thing your users want to see when they come to talk to you. So why showing a
459 traditional directory view? Choose yourself what you want they will see and how with this plugin.</p>
460461 <h3id="plugin-ci">CI</h3>
462 <p>Now that you understand your product is not only your code, you think that all of that require a lot of
463 process. And your right, transform md files to html, check that md files have good meta-data, users have
464 access to that branch or path... It' complex and require a complete workflow system, yes just like your
465 app. After all, is only lint, build and deploy. This plugin permit to lint and build your forge as
466 effectively as your project.</p>
467468 <h2>Plugins community</h2>
469470 <h3id="plugin-water">Water</h3>
471 <p>Water is the liquid needed to growth all plants on this planet. With this plugin every contributors received
472 some "water drops". With them, they can "bump" issues to choose what next is the best thing. This plugin add
473 gamification directly on your forge. And what is funny, is that as all your community is here, even
474 contributors which talk in your forum can received "water drops".</p>
475476 <h3id="plugin-forum">Forum</h3>
477 <p>Have your own Discourse for your product in your git repository.</p>
478479 <h3id="plugin-qa">Q&A</h3>
480 <p>Have your own StackOverflow for your product in your git repository.</p>
481482 <h3id="plugin-social">Social</h3>
483 <p>Send a linkedin post, tweet, toot, facebook post just by merging a request-pull. All your community can
484 create tweet and maintainers decides if and when to publish it.</p>
485486 <h2>Plugins stellars</h2>
487488 <h3id="plugin-mirror">Mirror</h3>
489 <p>Discoverability of your product will need to go through mastodonte forges... So with that plugin it's easy.
490 </p>
491492 <h3id="plugin-calendar">Calendar</h3>
493 <p>Organizing realeases, meetings or communication require to talk about time. With this plugin make a meeting
494 by doing a push. As it follow CalDAV protocol you can view your calendar in all compatible clients.</p>
495496 <h3id="plugin-importer">Importer</h3>
497 <p>With this plugin you can easily import your current project from others forges into GitRoot.</p>
498499 </section>
500501 <footer>
502 <pxmlns:cc="http://creativecommons.org/ns#">This work by <spanproperty="cc:attributionName">Romain
503 Maneschi</span> is licensed under <a504href="https://creativecommons.org/licenses/by-nc-sa/4.0/?ref=chooser-v1"target="_blank"505rel="license noopener noreferrer"style="display:inline-block;">CC BY-NC-SA 4.0<img506style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"507src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1"alt="CC"><img508style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"509src="https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1"alt="BY"><img510style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"511src="https://mirrors.creativecommons.org/presskit/icons/nc.svg?ref=chooser-v1"alt="NC"><img512style="height:22px!important;margin-left:3px;vertical-align:text-bottom;"513src="https://mirrors.creativecommons.org/presskit/icons/sa.svg?ref=chooser-v1"alt="SA"></a></p>
514 <p>Source on <ahref="https://gitlab.com/gitroot/gitroot">Gitlab</a>, soon on GitRoot!</p>
515 </footer>
516</body>
517518</html>