From 0e75581dd96f798784d6b19525846c752daf804a Mon Sep 17 00:00:00 2001 From: Aliaksandr Valialkin Date: Sun, 21 Apr 2024 00:00:10 +0200 Subject: [PATCH] docs: remove duplicate information regarding contribution guidelines to VictoriaMetrics Substitute duplicate information with the link to https://docs.victoriametrics.com/contributing/ across all the docs. --- README.md | 17 +---------- docs/CONTRIBUTING.md | 41 ++++++++++++++++++--------- docs/Cluster-VictoriaMetrics.md | 21 +------------- docs/FAQ.md | 4 +++ docs/README.md | 17 +---------- docs/Single-server-VictoriaMetrics.md | 17 +---------- 6 files changed, 36 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 6bfa0b300..d9b02c568 100644 --- a/README.md +++ b/README.md @@ -2622,22 +2622,7 @@ Feel free asking any questions regarding VictoriaMetrics: * [Google groups](https://groups.google.com/forum/#!forum/victorametrics-users) * [Mastodon](https://mastodon.social/@victoriametrics/) -If you like VictoriaMetrics and want to contribute, then we need the following: - -* Filing issues and feature requests [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). -* Spreading a word about VictoriaMetrics: conference talks, articles, comments, experience sharing with colleagues. -* Updating documentation. - -We are open to third-party pull requests provided they follow [KISS design principle](https://en.wikipedia.org/wiki/KISS_principle): - -* Prefer simple code and architecture. -* Avoid complex abstractions. -* Avoid magic code and fancy algorithms. -* Avoid [big external dependencies](https://medium.com/@valyala/stripping-dependency-bloat-in-victoriametrics-docker-image-983fb5912b0d). -* Minimize the number of moving parts in the distributed system. -* Avoid automated decisions, which may hurt cluster availability, consistency or performance. - -Adhering `KISS` principle simplifies the resulting code and architecture, so it can be reviewed, understood and verified by many people. +If you like VictoriaMetrics and want to contribute, then please [read these docs](https://docs.victoriametrics.com/contributing/). ## Reporting bugs diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2a856ddea..45963abf1 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -25,22 +25,11 @@ If you like VictoriaMetrics and want to contribute, then it would be great: - experience sharing with colleagues. - Convincing your management to sign [Enterprise contract](https://docs.victoriametrics.com/enterprise/) with VictoriaMetrics. -We are open to third-party pull requests provided they follow [KISS design principle](https://en.wikipedia.org/wiki/KISS_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](https://docs.victoriametrics.com/#profiling) - shows significant improvements in performance and scalability or significant reduction in RAM usage. - Profiling must be performed on [Go benchmarks](https://pkg.go.dev/testing#hdr-Benchmarks) and on production workload. -- Avoid [big external dependencies](https://medium.com/@valyala/stripping-dependency-bloat-in-victoriametrics-docker-image-983fb5912b0d). -- 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. +## Pull request checklist Before sending a pull request to [VictoriaMetrics repository](https://github.com/VictoriaMetrics/VictoriaMetrics/) please make sure it **conforms all** the following checks: +- The pull request conforms [`KISS` principle](https://en.wikipedia.org/wiki/KISS_principle). See [these docs](#kiss-principle) for more details. - The pull request contains clear description of the change, with links to the related GitHub issues and [docs](https://docs.victoriametrics.com/), if needed. - Commit messages contain concise yet clear descriptions. Include links to related GitHub issues in commit messages, if such issues exist. - All the commits are signed and include `Signed-off-by` line. Use `git commit -s` to include `Signed-off-by` your commits. @@ -80,3 +69,29 @@ Examples of good changelog messages: * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): add support for [VictoriaMetrics remote write protocol](https://docs.victoriametrics.com/vmagent/#victoriametrics-remote-write-protocol) when [sending / receiving data to / from Kafka](https://docs.victoriametrics.com/vmagent/#kafka-integration). This protocol allows saving egress network bandwidth costs when sending data from `vmagent` to `Kafka` located in another datacenter or availability zone. See [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/1225). * BUGFIX: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): suppress `series after dedup` error message in logs when `-remoteWrite.streamAggr.dedupInterval` command-line flag is set at [vmagent](https://docs.victoriametrics.com/vmgent.html) or when `-streamAggr.dedupInterval` command-line flag is set at [single-node VictoriaMetrics](https://docs.victoriametrics.com/). + +## KISS principle + +We are open to third-party pull requests provided they follow [KISS design principle](https://en.wikipedia.org/wiki/KISS_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](https://docs.victoriametrics.com/#profiling) + shows significant improvements in performance and scalability or significant reduction in RAM usage. + Profiling must be performed on [Go benchmarks](https://pkg.go.dev/testing#hdr-Benchmarks) and on production workload. +- Avoid [big external dependencies](https://medium.com/@valyala/stripping-dependency-bloat-in-victoriametrics-docker-image-983fb5912b0d). +- 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](https://docs.victoriametrics.com/cluster-victoriametrics/) has no the following "features" popular in distributed computing world: + +- Fragile gossip protocols. See [failed attempt in Thanos](https://github.com/improbable-eng/thanos/blob/030bc345c12c446962225221795f4973848caab5/docs/proposals/completed/201809_gossip-removal.md). +- Hard-to-understand-and-implement-properly [Paxos protocols](https://www.quora.com/In-distributed-systems-what-is-a-simple-explanation-of-the-Paxos-algorithm). +- Complex replication schemes, which may go nuts in unforeseen edge cases. See [replication docs](#replication-and-data-safety) 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. diff --git a/docs/Cluster-VictoriaMetrics.md b/docs/Cluster-VictoriaMetrics.md index 7a756b5dd..6ae32aa6b 100644 --- a/docs/Cluster-VictoriaMetrics.md +++ b/docs/Cluster-VictoriaMetrics.md @@ -1019,26 +1019,7 @@ Feel free asking any questions regarding VictoriaMetrics: * [Google groups](https://groups.google.com/forum/#!forum/victorametrics-users) * [Mastodon](https://mastodon.social/@victoriametrics/) -We are open to third-party pull requests provided they follow the [KISS design principle](https://en.wikipedia.org/wiki/KISS_principle): - -- Prefer simple code and architecture. -- Avoid complex abstractions. -- Avoid magic code and fancy algorithms. -- Avoid [big external dependencies](https://medium.com/@valyala/stripping-dependency-bloat-in-victoriametrics-docker-image-983fb5912b0d). -- Minimize the number of moving parts in the distributed system. -- Avoid automated decisions, which may hurt cluster availability, consistency or performance. - -Adhering to the `KISS` principle simplifies the resulting code and architecture, so it can be reviewed, understood and verified by many people. - -Due to `KISS`, cluster version of VictoriaMetrics has no the following "features" popular in distributed computing world: - -- Fragile gossip protocols. See [failed attempt in Thanos](https://github.com/improbable-eng/thanos/blob/030bc345c12c446962225221795f4973848caab5/docs/proposals/completed/201809_gossip-removal.md). -- Hard-to-understand-and-implement-properly [Paxos protocols](https://www.quora.com/In-distributed-systems-what-is-a-simple-explanation-of-the-Paxos-algorithm). -- Complex replication schemes, which may go nuts in unforeseen edge cases. See [replication docs](#replication-and-data-safety) 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. +If you like VictoriaMetrics and want contributing, then please read [these docs](https://docs.victoriametrics.com/contributing/). ## Reporting bugs diff --git a/docs/FAQ.md b/docs/FAQ.md index 244f6e5bb..2f9e962c0 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -33,6 +33,10 @@ Yes. See [these benchmarks](https://docs.victoriametrics.com/articles/#benchmark See [these docs](https://docs.victoriametrics.com/quick-start/). +## Hot to contribute to VictoriaMetrics? + +See [these docs](https://docs.victoriametrics.com/contributing/). + ## Does VictoriaMetrics support replication? Yes. See [these docs](https://docs.victoriametrics.com/cluster-victoriametrics/#replication-and-data-safety) for details. diff --git a/docs/README.md b/docs/README.md index 887ad8f86..ceb58995a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2625,22 +2625,7 @@ Feel free asking any questions regarding VictoriaMetrics: * [Google groups](https://groups.google.com/forum/#!forum/victorametrics-users) * [Mastodon](https://mastodon.social/@victoriametrics/) -If you like VictoriaMetrics and want to contribute, then we need the following: - -* Filing issues and feature requests [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). -* Spreading a word about VictoriaMetrics: conference talks, articles, comments, experience sharing with colleagues. -* Updating documentation. - -We are open to third-party pull requests provided they follow [KISS design principle](https://en.wikipedia.org/wiki/KISS_principle): - -* Prefer simple code and architecture. -* Avoid complex abstractions. -* Avoid magic code and fancy algorithms. -* Avoid [big external dependencies](https://medium.com/@valyala/stripping-dependency-bloat-in-victoriametrics-docker-image-983fb5912b0d). -* Minimize the number of moving parts in the distributed system. -* Avoid automated decisions, which may hurt cluster availability, consistency or performance. - -Adhering `KISS` principle simplifies the resulting code and architecture, so it can be reviewed, understood and verified by many people. +If you like VictoriaMetrics and want to contribute, then please [read these docs](https://docs.victoriametrics.com/contributing/). ## Reporting bugs diff --git a/docs/Single-server-VictoriaMetrics.md b/docs/Single-server-VictoriaMetrics.md index 198772a5f..e83be4aa3 100644 --- a/docs/Single-server-VictoriaMetrics.md +++ b/docs/Single-server-VictoriaMetrics.md @@ -2633,22 +2633,7 @@ Feel free asking any questions regarding VictoriaMetrics: * [Google groups](https://groups.google.com/forum/#!forum/victorametrics-users) * [Mastodon](https://mastodon.social/@victoriametrics/) -If you like VictoriaMetrics and want to contribute, then we need the following: - -* Filing issues and feature requests [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). -* Spreading a word about VictoriaMetrics: conference talks, articles, comments, experience sharing with colleagues. -* Updating documentation. - -We are open to third-party pull requests provided they follow [KISS design principle](https://en.wikipedia.org/wiki/KISS_principle): - -* Prefer simple code and architecture. -* Avoid complex abstractions. -* Avoid magic code and fancy algorithms. -* Avoid [big external dependencies](https://medium.com/@valyala/stripping-dependency-bloat-in-victoriametrics-docker-image-983fb5912b0d). -* Minimize the number of moving parts in the distributed system. -* Avoid automated decisions, which may hurt cluster availability, consistency or performance. - -Adhering `KISS` principle simplifies the resulting code and architecture, so it can be reviewed, understood and verified by many people. +If you like VictoriaMetrics and want to contribute, then please [read these docs](https://docs.victoriametrics.com/contributing/). ## Reporting bugs