Re: adding src/README.md

[coypu%sdf.org@localhost]

On Wed, Oct 10, 2018 at 11:31:43AM +0200, Kamil Rytarowski wrote:
> I'm in favor of plain text (README without .md extension) that is
> syntactically markdown compatible and in the same time not hyped with a
> currently popular format, file extensions or the currently popular set
> of extensions for Markdown (GitHub uses so called "Flavored Markdown",
> probably everybody uses a set of extensions).
> 
> This plain text will be forward compatible.
> 
> (Also Markdown is triggering some people, especially in the *roff
> circles. Additionally Markdown is not the only one supported by GitHub,
> there are rdoc, textile, org, creole, rst, asciidoc etc.)
> 

I don't have a strong opinion on documentation formats, other than
README.md carries a big benefit. I've mentioned that "introduction user
time is very important", and markdown helps me shave a small amount of
time by having [text](link), which allowed e.g. to insert an IRC webchat
link at no cost, which benefits people who are not familiar with
freenode on IRC.

If GitHub tomorrow decides to only display text written backwards, I'll
rewrite it backwards without even questioning it.

> I would reuse the existing project description rather than crafting
> something new from scratch with biased usage options.
> 
> I've copy-pasted project description and stored it here:
> 
> http://netbsd.org/~kamil/README
> 
> It contains quick introduction, explanation what is the project about,
> building introduction, testing introduction and useful resources.
> 
> I've omitted: biased command line for building the release, currently
> popular mirror and currently popular VCS.
> 

I am however very opinionated about the choices made here.
- The existing project description is very long. The second section here
is more characters than my entire README.md, without even accounting
for URLs.
I've made a similar change to the homepage:
http://cvsweb.netbsd.org/bsdweb.cgi/htdocs/index.html?rev=1.1982&content-type=text/x-cvsweb-markup

- Similarly, you've spent 8 lines of text describing what tests are for,
and 5 lines of text on implementation details of our testing framework.
That kind of information is only relevant once I am interested in
copying or modifying the tests.
It isn't hard to reach information about test details once you know about
'atf-run |atf-report', all our documentation is available as man
<command>, and man atf-run / atf-report cross-reference atf(7).

- I realize that my own build.sh command is very opinionated, but I
think it's more important to have a command that you can copy and will
work or nearly work for many users than to be neutral.

- The argument to dropping anoncvs makes sense if viewed from an active
mirror already, but I am considering the case where the mirror becomes
out of date (e.g. a fork).
AnonCVS isn't a personal preference, but the closest thing to a
canonical source that is publicly accessible.
The very day we change away from CVS I will happily change it :-)

- Ideally, for most users, building will work right away. I don't want
to give them any indication it won't.
If we want to warn them that a C++ compiler is necessary, I would
prefer to do it via a quick sanity test in build.sh (or another
script) than pay the cost in documentation.
Similarly, I've made a change to warn if ./build.sh -x is used without
an appropriate xsrc.

- I agree that a description of the source tree might be handy. I'd
rather do it differently and take advantage of whitespace where
possible, and only mention the directories more commonly edited, e.g. a
first try:

sys/		kernel sources
sys/dev		device drivers
sys/arch	architecture-specific code
usr.bin/	sources for programs in /usr/bin
external/	software maintained outside of NetBSD (like the compiler)

[man hier(7)](valid URL to man hier) includes more detail.

The intention here is:
Omit usr.sbin/, bin/, sbin/ descriptions by mentioning only one of the
cases, the rest can be inferred.
tools/ is rarely something that people have to edit, so it's not worth
mentioning.

And so on.
I hope that the additional details about why I make the opinionated
decisions help to explain why I have done things that way. While my
README.md is short, it went through multiple revisions and received some
feedback. I carefully thought about why to do things that way.