docs: move dev instructions to a wiki

[n0toose]

We should use everything currently under Contributing in the README.md file for a BUILDING.md. I initially just created a separate section so as to avoid touching on this subject when I expanded the building instructions, but if we start including more instructions for maintainers and prospective contributors, this copy-paste job might be necessary.

Needed for: #799
Currently blocked by: #796 (which modifies the instructions by removing the -v parameter)

[jounathaen]

What's the purpose and the benefit of a Building.md?
I'd agree that these sections don't necessarily belong to the README, but a wiki feels like the better place for me.

[mkroening]

A third suggestion: I'd personally prefer a CONTRIBUTING.md file (see tokio's for example) over a wiki since the information is then included in the git repo and can be searched in more easily online and locally.

[jounathaen]

Well, I think a CONTRIBUTING.md fulfills a slightly different purpose. In my experience, that one is about the "social" guidelines (how to bug report, how to style your commit messages, code of conduct...).
These guidelines can definitely be very useful in large repositories with plenty of outside contributors, but I don't see an actual issue with this for the Hermit repositories (yet 😉).

I think @n0toose talks about some development guidelines (how to build uhyve, how to set up vscode, how to run tests...).
I'm slightly hesitant to put those in the codebase, as I see them getting outdated quickly, but I don't have a strong opinion on this topic.

[n0toose]

See: https://github.com/nodejs/node/blob/main/BUILDING.md

[n0toose]

These guidelines can definitely be very useful in large repositories with plenty of outside contributors, but I don't see an actual issue with this for the Hermit repositories (yet 😉).

We already do have some text explaining how the development process is supposed to work, and I'd like to expand it with details such as a brief mention on benchmarks or being able to test it with your own binaries. (For instance, I didn't know what hermit-rs was when I first got started.)

I'm somewhat confident that there is a good way to do this (e.g. strictly brief sentences of what a test-kernel is) and that there's a good reason to (external contributors have existed, it helps non-external ones too), but it's easier to write a sentence and show it to you than say how I'd write the sentence. No matter the details, we should split the file first and argue the details later, as there is objectively a part of the README that is better off elsewhere. If we use CONTRIBUTING.md (this is what I think of when I think of one) for the filename, well, that's an OK compromise for me.

I'd agree that these sections don't necessarily belong to the README, but a wiki feels like the better place for me.

AFAIK the wiki is another Git repository in the background, which is very cursed and history (including in Hermit) shows that people just forget about the "Wiki" tab after a while and it just doesn't get maintained anymore. Although I understand why it might seem like it's convenient to separate code and docs, in practice, the wiki is too invisible and too much trouble because of the need to use a web editor. It also doesn't use the "GitHub review model", the changes don't attract attention, nobody says "make sure to edit the wiki after your change is merged" and you don't care about changing them when changing something locally.

A wiki is arguably very useful if you have many components and non-technical end users. However, this is why wikis are better-suited for big projects. In principle, they require discipline (and we'd both agree that "we" don't necessarily [want to] have it), complicated permission management and increase vendor lock-in.

[jounathaen]

Suggestion:

• We start with a Wiki
• We link the Wiki in the README
• If the content about building and developing uhyve in the wiki is sufficiently stable, we can include it as a BUILDING.md.

I just want to avoid more unmaintained/outdated documentation files in the repository.

[n0toose]

Let's take a breather and discuss the details at a later point in time. I'll try to concentrate on some greater priorities for the time being and discuss details later, perhaps in person.

[jounathaen]

Wiki is activated now, feel free to modify!