Create development guide

[madolson]

I'm just starting an issue to dump all of the conversations we've had about getting started as a developer on Valkey. At some point we should commit them to a markdown, but just wanted to start taking notes since I've seen a few examples of best practices/naming conventions/common pitfalls.

General coding guidelines.

1. Most of the style comments are enforced by clang format.
2. C style comments /* comment */ can be used for both single and multi-line comments. C++ comments // can only be used for single line comments.

Naming conventions

Valkey has a long history of inconsistent naming conventions. Generally follow the style of the surrounding code, but you can also always use the following conventions for variable and structure names:

• Variable names: snake_case or all lower case (valkeyobject or valkey_object)
• Function names: camelCase or namespace_camelCase (createObjectList or networking_createObjectList).
• Macros: UPPER_CASE (DICT_CREATE)
• structures: camelCase (user)

Best practices

1. Avoid adding configuration when a feature can be fully controlled by heuristics. We want Valkey to work correctly out of the box without much tuning. When the workload characteristics can't be inferred or imply a tradeoff (CPU vs memory), then provide a configuration.

[sarthakaggarwal97]

We can also include the minimum test / functional coverage required, and how can we write / run TCL tests (maybe)?

[ranshid]

Some things that came to mind:

1. use of static functions when possible and internal to the object
2. architecture specific definitions: where to place them/ which architectures should be supported/ which compiler flavors etc...
3. regarding configurations, maybe we should help programers decide when feature control should be supported by config or debug command (eg tests)
4. makefile/Cmake conventions (?)

[pieturin]

We should specify that we want to keep line lengths to max 120 characters.

[enjoy-binbin]

We should specify that we want to keep line lengths to max 120 characters.

90 chars? i think 120 is still quite long and hard to read the long sentence for me (bad at reading)

[enjoy-binbin]

also, i think we should mention the backport thing? How do we do the backport now? Do we do the backport when a PR got merged like #1575? Or we just mark a label and when the release date come, someone from the trusted list do the local cherry-pick thing and push they together?

[hpatro]

also, i think we should mention the backport thing? How do we do the backport now? Do we do the backport when a PR got merged like #1575? Or we just mark a label and when the release date come, someone from the trusted list do the local cherry-pick thing and push they together?

That's a good question. I think it's much better if the developer who fixed/submitted the PR to unstable can also backport it to the release branches as they can deal with the merge conflicts better and then the trusted list of people can review and merge it. What are your thoughts @enjoy-binbin ?

[sarthakaggarwal97]

I think it's much better if the developer who fixed/submitted the PR to unstable can also backport it to the release branches as they can deal with the merge conflicts better

I agree. We can also have a bot that can raise the backport PRs (using cherry-picks, so the commit is technically already reviewed), incase there is no conflict if the backport label is present?

[enjoy-binbin]

I think it's much better if the developer who fixed/submitted the PR to unstable can also backport it to the release branches as they can deal with the merge conflicts better and then the trusted list of people can review and merge it.

I don't like too many PRs. But you are right the developer can handle the conflicts better, it increases the operation of normal users. Determining whether a commit needs a backport often requires someone who is very familiar with it, and it need to know the backport rule. Sadly right now we dont seem to have a clear boundary to divide it now, and it is often those of us who are more familiar with it who decide whether a backport is needed.

I kind of like the idea of doing all the cherry-pick at the end. We know what we backported in the end, and some things may change over time. And indeed, the conflicts is a pain, but maybe those things with big confilcts should not be backported. We need to consider this when merging, separate the fixes and refactorings, and we need to modify the backport as litter as possible. Because it is not only us who need to backport, other peoples's forks, such as our internal forks, also requrie the backport. It is very painful to deal with the confilcts if the confilcts are big. Fortunately, each of our commits has its own tests, which makes this backport operation relatively safe.

[hpatro]

@valkey-io/core-team Please add your opinion on backport PRs. Will be good to have a guideline defined soon.

[zuiderkwast]

We'll probably need to decide manually which PRs need to be backported, but a semi-automatic bot could improve the process. I like the idea of a bot that opens a cherry-pick PR targeting a backport branch. Note that we have multiple old versions and each PR may need backporting to one or more of the old version branches, for example to 8.0 and 7.2, or only to 8.0.

When we make a release, we need to update the release notes too, and a few more things: https://github.com/valkey-io/valkey/wiki/Releasing-a-new-Valkey-version.