valkey/DEVELOPMENT_GUIDE.md

Valkey development guidelines

This document provides a general overview for writing and designing code for Valkey. During our long development history, we've made a lot of inconsistent decisions, but we strive to get incrementally better.

General Best practices

1. Try to limit the number of lines changed in a PR when possible. We do a lot of backporting as a project, and the more lines changed, the higher the chance of having to resolve merge conflicts. Please separate refactoring and functional changes into separate PRs, to make it easier to handle backporting.
2. 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. Configurations can be added to provide additional tuning of features. When the workload characteristics can't be inferred or imply a tradeoff (CPU vs memory), then provide a configuration.

General style guidelines

Most of the style guidelines are enforced by clang format, but some additional comments are included here.

1. C style comments /* comment */ can be used for both single and multi-line comments. C++ comments // can only be used for single line comments. Multi line comments should have the leading * align and the final */ should be on the same line as the last line of text. e.g.

/* Blah Blah
 * Blah Blah. */

2. Comments should generally be used to describe behavior that is not obvious from reading the code itself. This includes complex behavior, why code was written the way it was and describing non-obvious behavior. Additionally, functions should be documented to explain all of the function's behavior without having to read the code.
3. Generally keep line lengths below 90 characters when reasonable, however there is no explicit line length enforcement. Use your best judgement for readability.
4. Use static functions when a function is only intended to be accessed from the same file. For historical reasons, some private functions are prefixed by _, and they are kept as is to make it easier to backport changes.
5. Use the boolean type for true/false values. For historical reasons, some functions used the integer type, and they are kept as is to make it easier to backport changes.

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 for short names (e.g. cached_reply or keylen).
• Function names: camelCase or namespace_camelCase (e.g. createStringObject or IOJobQueue_isFull).
• Macros: UPPER_CASE (e.g. MAKE_CMD).
• Structures: camelCase (e.g. user).

Licensing information

When creating new source code files, use the following snippet to indicate the license:

/*
 * Copyright (c) Valkey Contributors
 * All rights reserved.
 * SPDX-License-Identifier: BSD-3-Clause
 */

If you are making material changes to a file that has a different license at the top, also add the above license snippet. There isn't a well defined test for what is considered a material change, but a good rule of thumb is that material changes are more than 100 lines of code.

Test coverage

Valkey uses two types of tests: unit and integration tests. All contributions should include a test of some form.

Unit tests are present in the src/unit directory, and are intended to test individual structures or files. For example, most changes to data structures should include corresponding unit tests.

Integration tests are located in the tests/ directory, and are intended to test end-to-end functionality. Adding new commands should come with corresponding integration tests. When writing cluster mode tests, do not use the legacy tests/cluster framework, which has been deprecated, and instead write tests in unit/cluster.

Documentation

Valkey keeps most of the user documentation in the valkey-doc repository in a few areas:

1. Major functionality is documented in the topics section.
2. Specific command behavior is documented in the commands section. Command history is also documented in the command json file.
3. Server info fields are documented in the INFO command.

When a PR is opened that requires documentation to be updated, the needs-doc-pr should be added until the corresponding documentation PR is open.

Adding INFO fields

An INFO field is a name:value line in the output of the INFO command. Fields are grouped into sections, each starting with a header line such as # Server or # Memory. Users and monitoring tools parse these fields.

The following are best practices for adding INFO fields:

• Keep the number of INFO fields small.
• Before adding a metric, check whether users can derive it from existing fields.
• Prefer counters over gauges. Counters let monitoring systems compute changes over time, while gauges can miss short spikes that happen between samples.
• Choose the section for a new field based on the intended audience and whether the field is expected to remain stable:
  • Metrics that are broadly useful to users belong in a default section, returned by INFO and INFO default. Document these fields in the INFO command documentation.
  • Stable metrics for specific features or less common troubleshooting needs belong in a non-default section. Document these fields too. Non-default server sections are included in INFO all, which monitoring tools may collect, so avoid adding unnecessary fields just because a section is not returned by default.
  • Internal debugging metrics that may change or be removed belong in the debug section and are not part of the user documentation. This section must be requested explicitly with INFO debug; it is excluded from INFO, INFO all, and INFO everything.