VictoriaMetrics/docs/CONTRIBUTING.md

weight	title	menu	aliases
400	Contributing	docs identifier parent weight vm-contributing victoriametrics 400	/CONTRIBUTING.html

If you like VictoriaMetrics and want to contribute, then it would be great:

• Joining VictoriaMetrics community Slack (Slack inviter and Slack channel) and helping other community members there.
• Filing issues, feature requests and questions at VictoriaMetrics GitHub.
• Improving VictoriaMetrics docs. See how to update docs here.
• Spreading the word about VictoriaMetrics via various channels:
  • conference talks
  • blogposts, articles and case studies
  • comments at Hacker News, Twitter, LinkedIn, Reddit, Facebook, etc.
  • experience sharing with colleagues.
• Convincing your management to sign Enterprise contract with VictoriaMetrics.

Issues

When making a new issue, make sure to create no duplicates. Use GitHub search to find whether similar issues exist already. The new issue should be written in English and contain concise description of the problem and environment where it exists. We'd very much prefer to have a specific use-case included in the description, since it could have workaround or alternative solutions.

When looking for an issue to contribute, always prefer working on bugs instead of enhancements. Helping other people with their questions is also a contribution.

If you'd like to contribute to documentation please read the guideline.

Labels

We use labels to categorize GitHub issues. We have the following labels:

1. A component label: vmalert, vmagent, etc. Add this label to the issue if it is related to a specific component.
2. An issue type: bug, enhancement, question.
3. enterprize, assigned to issues related to ENT features
4. need more info, assigned to issues which require elaboration from the issue creator. For example, if we weren't able to reproduce the reported bug based on the ticket description then we ask additional questions which could help to reproduce the issue and add need more info label. This label helps other maintainers to understand that this issue wasn't forgotten but waits for the feedback from user.
5. waiting for release, assigned to issues that required code changes and those changes were merged to upstream, but not released yet. Once a release is made, maintainers go through all labeled issues, leave a comment about the new release, remove the label, and close the issue.
6. vmui, assigned to issues related to https://docs.victoriametrics.com/#vmui or https://docs.victoriametrics.com/victorialogs/querying/#web-ui

Pull request checklist

Implementing a bugfix or enhancement requires sending a pull request to the corresponding repository.

A pull request should contain the following attributes:

1. Don't use master branch for making PRs, as it makes it impossible for reviewers to modify the change.
2. All commits need to be signed.
3. A clear and concise description of what was done and for what purpose.
4. A link to the issue related to this change, if any.
5. Tests proving that the change is effective. See this style guide for tests. To run tests and code checks locally execute commands make tests-full and make check-all.
6. Try to not extend the scope of the pull requests outside the issue, do not make unrelated changes.
7. Documentation update, if needed. For example, adding a new flag or changing behavior of existing flags or features requires reflecting these changes in the documentation. For new features add {{%/* available_from "#" */%}} shortcode to the documentation. It will be later automatically replaced with an actual release version.
8. A line in the changelog mentioning the change and related issue in a way that would be clear to other readers even if they don't have the full context.
9. Reviewers who you think have the best expertise on the matter.

See good example of pull request here.

To merge the PR it should be approved by at least one reviewer, all CI checks should be green.

Once the PR is merged, check if related issues are still opened (GitHub may close it on PR merge). The issue should be closed only when the change gets included into an actual release.

Label waiting for release is added to issues related to the merged PR. It makes easier for the person who makes the release to track the related tickets and update them once release is published.

KISS principle

We are open to third-party pull requests provided they follow KISS design principle.

• Prefer simple code and architecture.
• Avoid complex abstractions.
• Avoid magic code and fancy algorithms.
• Apply optimizations, which make the code harder to understand, only if profiling shows significant improvements in performance and scalability or significant reduction in RAM usage. Profiling must be performed on Go benchmarks and on production workload.
• Avoid big external dependencies.
• Minimize the number of moving parts in the distributed system.
• Avoid automated decisions, which may hurt cluster availability, consistency, performance or debuggability.

Adhering KISS principle simplifies the resulting code and architecture, so it can be reviewed, understood and debugged by wider audience.

Due to KISS, cluster version of VictoriaMetrics has none of the following "features" popular in distributed computing world:

• Fragile gossip protocols. See failed attempt in Thanos.
• Hard-to-understand-and-implement-properly Paxos protocols.
• Complex replication schemes, which may go nuts in unforeseen edge cases. See replication docs for details.
• Automatic data reshuffling between storage nodes, which may hurt cluster performance and availability.
• Automatic cluster resizing, which may cost you a lot of money if improperly configured.
• Automatic discovering and addition of new nodes in the cluster, which may mix data between dev and prod clusters :)
• Automatic leader election, which may result in split brain disaster on network errors.