☂️ Renew Tarantool Core developer guidelines (aka Contribution Guide)

[Totktonada]

https://www.tarantool.io/en/doc/latest/dev_guide/

There are a lot of questions to the current developer guides.

1. There is no any forewords or landing page.
2. There are a lot of articles, which does not correspond to the topic, at least:
   • C API reference.
   • Binary protocol (and why it is under 'internals' section?)
   • Startup with replication.
   • Recovery process.
   • Release management (and it should be 'release policy', without recipes how to push tags and so on).
3. Why we have Python style guide? Isn't PEP-8 sufficient? Are we have significant amount of Python code somewhere?
4. The section is named as dev_guide in the URL, but the page is named as 'Contributor's Guide', but it contains 'Developer guidelines'... what a hell?
5. More about this 'Developer guidelines' page:
   • 'How to work on a bug' section is entirely for employees: at least it assumes ability to set labels on issues. And it almost entirely obsoloted: starting from Launchpad mention ([1pt] Launchpad mentions seem to be obsoleted #448) and ending with assumption that a each developer can push a commit to master.
   • A lot of details how to use email for sending a patch, but it is completely irrelevant when one use PRs.
   • It does not mention @TarantoolBot documentation tasks automation and does not mention changelog entries that should accompany are user-visible change.
6. The C style guide looks unmaintained (at least because of [3pt] Cleanup Tarantool C Style Guide #1031).
7. There is 'Build and contribute' section (which contains 'Building from source' and 'Release management', what?..), but 'Developer guidelines' is outside of it: in 'Guidelines' section.
8. 'Building from source' looks unmainlained. And it maybe should be just in README of the repository.

There is no any structure in this hell. It is outdated. And, so, it requires significant effort to understand.

There is also 'How to be involved in Tarantool' page. Let's give a glance:

1. First of all, it surprisingly in a different namespace (/contributing/).
2. It is too big to be a landing page (and there is no ToC), but misses a lot of details to be a guide.
3. Some of sections are in 'How to' style, but some are a kind of 'just information' with very sketchy info.
4. Attempt to describe tests in Tarantool is failed: it refers to 'core = app' test and missed 'core = tarantool' ones. The section is called 'how to write a test', but it does not answer ever on the question, where I should place a testing code: new file? existing one? How to name the file? How to run just one test?
5. 'How to contribute to connectors / modules / tools' do not have information how to contribute to them.
6. What makes me mad: 'Maintainers are people who can merge PRs or commit to master'. Nothing about responsibility. It seems, this page was 'just merged to master' by a 'maintainer'.
7. A lot of self-repeating. Strange.
8. A lot of links to Artur's Telegram. Some google forms. That's strange too.

I extracted a set of topics from different sources we have. I guess we can use them to define a meaningful documentation structure.

Topics from SOP (our internal document for developers):

• How to download, build, run tests.
• How to send a patch / PR.
• Details regarding emailing patches (it should be its own section, really; it mostly useless in context of PRs; see also Declare that simple PRs for core will be reviewed  #1443).
• How to report a bug (we have the similar page on the website in /admin/ namespace).
• How to propose an RFC document.
• How to write a commit message.

Topics from the website docs (ones that I criticize above):

• How to report a bug (here).
• How to write a commit message.
• How to communicate around review.
• C style guide.
• Lua style guide.

From 'Code review procedure' wiki page:

• C code style (it should in one place).
• How to write a test.
• How to write a commit message.
• General coding points.
• Details regarding emailing patches.
• How to communicate around review.
• Tips for self-review.

From 'How to be involved in Tarantool' page:

• How to ask a question.
• How to file an issue.
• Different communication channels.
• Ecosystem structure or something like so.
• How to file issue / PR re docs.
• Sketchy info re modules.
• How to contribute to Tarantool Core.
• How to write a test.
• Sketchy info re connectors.
• Sketchy info re tools.
• 'Maintainers are people who can merge PRs or commit to master'.

See, a lot of information is duplicated: say, 'developer guidelines' learn us how to write a commit message, but 'code review procedure' do the same. 'C style guide' describes the style, but 'code review procedures' do the same. And again in SOP. In my understanding, the information should be organized in meaningful categories and should not be repeated. If we'll feed the same information to a reader several times, (s)he will lost concentration and will miss new details.

Keep in the mind, that a new structure should have a room for future guides around modules / connectors and so on (everything aside Tarantool Core).

Don't forget to setup appropriate redirects after the restructurization of the guidelines pages.

Part of the general direction toward new contributors. The umbrella issue is #1444.

[Totktonada]

A bit more examples, why it looks unmaintained: #1494, #993.

[Totktonada]

There is also 'Developer information' wiki page, which looks quite outdated.

[veod32]

Scope of work for updating Contribution Guide (CG) seems much bigger than 1 sprint so my proposal is:

1. To have this ticket as the umbrella ticket and aggregator for smaller subtasks.
2. After having the TOC ([8pt] [Contribution Guide]: scope analysis, TOC #1673), estimate different TOC chapters and have them as the subtasks that can be put in spints.

In other words, to eat this big elephant (this ticket) in smaller portions.

[artur-barsegyan]

As I understand it, we came to the conclusion that this should be written by the core command.

@Totktonada Do you agree with it?

[Totktonada]

I didn't hear about this.

[patiencedaur]

Hi @Totktonada,
Like Artur, I also heard (from @NickVolynkin) that the developer guidelines are to be maintained by the Core team. Is that true and what is the situation now?

[Totktonada]

It seems, it is not really maintained by anybody. Let's fight for the work?

[patiencedaur]

@Totktonada, I'll pass C, Python, and Lua style guides to you without a fight---they're basically internal documents now. You can put them in tarantool/wiki, as we recenly discussed. Let's talk about everything else in Q2--Q3, when we have more resources.

[pgulutzan]

@patiencedaur: So far there is no need for an SQL style guide, but if lots of users start to write with Tarantool/SQL then we should write or reference something, someday. My look at the matter is https://github.com/pgulutzan/descriptive-sql-style-guide/blob/master/style.md

[patiencedaur]

@pgulutzan Thank you! That looks like a comprehensive comparative research on SQL style guides. But this is not a style guide :)

@Totktonada How do we estimate how many users write with Tarantool/SQL? Do you think we're at the stage where an SQL style guide should be included in the wiki?