Documenting things related to the meshnet
cjdns addresses a large number of complex issues in an elegant way. While efforts have been made to provide a default configuration that matches the greatest number of use cases, it is impractical to expect software to replace understanding.
Enter the documentation project...
The good citizens of Hyperboria decided to put together this collection of documentation to help make the inner workings of cjdns more transparent.
We want you to get involved! Feel free to submit pull requests.
See index.md for current progress. We'd love more languages!
Also have a look at Prose for Programmers, a work-in-progress book aimed at helping software developers write better prose.
We are interested in documenting a range of topics:
- cjdns internals: bugs and features
- operator culture and best practices
- meshlocal resources
- introductory literature
cjd would rather write code than troubleshoot trivial issues which often turn out to have resulted from user error. To make this easier, a few members of the community have offered to investigate issues on his behalf.
If you think you've found a bug, report it on our fork's issue tracker. We'll try to gather up documentation related to the issue, to better understand where it might be coming from. Once we can narrow it down, and research some of the background details to that particular piece of functionality, we may be able to submit patches ourselves.
Anything you can submit that gets us closer to understanding some bug or function within cjdns is welcome. By starting an inquiry, you make it just a little bit easier for someone else to continue it. With that in mind, please read this note on reporting bugs and our more general contribution policy. Get involved!
Unless otherwise noted, the contained documents are licensed under a Creative Commons Attribution 4.0 Unported License.
See LICENSE.txt, or <creativecommons.org/licenses/by/4.0/>
Please remember that the canonical repo is at gitboria.com/projectmeshnet/documentation in Hyperboria. Pull from there, and push there first. If the canonical repo and mirror at github.com/hyperboria/docs diverge, the canonical repo's respective branch shall be force-pushed to the mirror.
If you must create a new file, come talk to us on irc.fc00.io #documentation about where it should be located. If it deals with configuration of cjdns or the host system, it should be located in config/. Installation guides go in install/, bugs or quirks go in bugs/. Files must adhere to the existing naming scheme: lower-case-with-hyphens.md if they are to be accepted into the repository.
This repository is semi-regularly merged into cjdns' doc/ directory.
It's useful to ship documentation with the code.
We use the following commands.
$ cd cjdns/
$ git remote add hyperboria [email protected]:hyperboria/cjdns.git
$ git remote add docs [email protected]:projectmeshnet/docs.gitTo merge documentation changes into cjdns, we squash all new commits since the last merge into one commit, and merge that commit into master.
$ git checkout master
$ git pull hyperboria master
$ git subtree pull --squash -P doc/ docs/master
$ git push hyperboria masterTo merge documentation changes in cjdns back upstream into this repository, we create a merge commit, and push it.
$ git subtree split -P doc/
38e3bc6f899de49213aed754c74046b9ae4a85d2
$ git push docs 38e3bc6f:master