How should CockroachDB open source contributors leverage the existing design documentation?

General
#1

There are four sources of documentation talking about CockroachDB’s architecture and internals:

  1. Architecture Overview and detailed for various layers
  2. design.md in source code
  3. CockroachDB technical notes
  4. RFCS

And 2. says:

It may not always be completely up to date.

So my understanding is that 1. is a high-level description and much more updated. 2. is more oriented to open source contributors and slightly outdated. So if I want to know more details, I still need to read 2. even though it is outdated.

Is my understanding correct?

And I think that it will help new open source contributors a lot if there is a guide about how to use the above four sources of documentation.

#2

Hi @yaojingguo,
Good question! Yes, your understanding is correct. RFCs give the most up-to-date picture but it takes time to get their changes reflected in high-level docs like (1) and (2).

We have this contribution guide, but it doesn’t reference those docs; we should probably add a section about them. Filed https://github.com/cockroachdb/docs/issues/2811 to add it.

#3

@vilterp Look forward to such a section.