From b16dbab137b6654c9556e129a8c4440ff050ed13 Mon Sep 17 00:00:00 2001 From: Aliaksandr Valialkin Date: Sat, 20 Apr 2024 23:06:37 +0200 Subject: [PATCH] Move CONTRIBUTING.md to docs/ It is better from visibility PoV if the CONTRIBUTING.md file is visible at https://docs.victoriametrics.com/contributing/ . This page can be indexed by search engines and searched by our users later. It is also easier to provide a link to this page now comparing to the old link, which is much harder to remember: https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/CONTRIBUTING.md While at it, syncrhonize docs/CONTRIBUTING.md with .github/PULL_REQUEST_TEMPLATE/pull_request_template.md , so they do not contain duplicate information, which can be outdated over time. Now all the relevant information is located at docs/CONTRIBUTING.md, while .github/PULL_REQUEST_TEMPLATE/pull_request_template.md refers this doc. This is a follow-up for c006db1798ca6343aa9354e470d16df84cb616ec Updates https://github.com/VictoriaMetrics/VictoriaMetrics/pull/6040 --- .../pull_request_template.md | 30 +------ CONTRIBUTING.md | 22 +----- docs/CONTRIBUTING.md | 79 +++++++++++++++++++ 3 files changed, 82 insertions(+), 49 deletions(-) create mode 100644 docs/CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index f50a618eb..e072298c8 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -4,32 +4,6 @@ Please provide a brief description of the changes you made. Be as specific as po ### Checklist -The following checks are mandatory: +The following checks are **mandatory**: -- [ ] I have read the [Contributing Guidelines](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/CONTRIBUTING.md) -- [ ] All commits are signed and include `Signed-off-by` line. Use `git commit -s` to include `Signed-off-by` your commits. See this [doc](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) about how to sign your commits. -- [ ] Tests are passing locally. Use `make test` to run all tests locally. -- [ ] Linting is passing locally. Use `make check-all` to run all linters locally. - -Further checks are optional for External Contributions: - -- [ ] Include a link to the GitHub issue in the commit message, if issue exists. -- [ ] Mention the change in the [Changelog](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/docs/CHANGELOG.md). Explain what has changed and why. If there is a related issue or documentation change - link them as well. - - Tips for writing a good changelog message:: - - * Write a human-readable changelog message that describes the problem and solution. - * Include a link to the issue or pull request in your changelog message. - * Use specific language identifying the fix, such as an error message, metric name, or flag name. - * Provide a link to the relevant documentation for any new features you add or modify. - -- [ ] After your pull request is merged, please add a message to the issue with instructions for how to test the fix or try the feature you added. Here is an [example](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4048#issuecomment-1546453726) -- [ ] Do not close the original issue before the change is released. Please note, in some cases Github can automatically close the issue once PR is merged. Re-open the issue in such case. -- [ ] If the change somehow affects public interfaces (a new flag was added or updated, or some behavior has changed) - add the corresponding change to documentation. - - -Examples of good changelog messages: - -1. 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). - -2. 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/). +- [ ] My change adheres [VictoriaMetrics contributing guidelines](https://docs.victoriametrics.com/contributing/). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 342dda10d..efcebc815 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1 @@ -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. - -Before sending a pull request please check the following: -- [ ] All commits are signed and include `Signed-off-by` line. Use `git commit -s` to include `Signed-off-by` your commits. See this [doc](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) about how to sign your commits. -- [ ] Tests are passing locally. Use `make test` to run all tests locally. -- [ ] Linting is passing locally. Use `make check-all` to run all linters locally. +The document has been moved [here](https://docs.victoriametrics.com/contributing/). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 000000000..e3e85a23b --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,79 @@ +--- +sort: 400 +weight: 400 +title: Contributing to VictoriaMetrics +menu: + docs: + parent: 'victoriametrics' + weight: 400 +aliases: +- /CONTRIBUTING.html +--- + +# Contributing to VictoriaMetrics + +If you like VictoriaMetrics and want to contribute, then it would be great: + +- Joining VictoriaMetrics community Slack ([Slack inviter](https://slack.victoriametrics.com/) and [Slack channel](https://victoriametrics.slack.com/)) + and helping other community members there. +- Filing issues, feature requests and questions [at VictoriaMetrics GitHub](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). +- Improving [VictoriaMetrics docs](https://docs.victoriametrics.com/). The docs' sources are located [here](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/docs). +- Spreading the word about VictoriaMetrics via various channels: + - conference talks + - blogposts, articles and [case studies](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/docs/CaseStudies.md) + - comments at Hacker News, Twitter, LinkedIn, Reddit, Facebook, etc. + - 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. + +Before sending a pull request to [VictoriaMetrics repository](https://github.com/VictoriaMetrics/VictoriaMetrics/) please check the following: + +- [ ] 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. + See this [doc](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) about how to sign your commits. +- [ ] Tests are passing locally. Use `make test` to run all tests locally. +- [ ] Linting is passing locally. Use `make check-all` to run all linters locally. +- [ ] If the change fixes some bug, it would be great to cover it by [tests](https://pkg.go.dev/testing) (if it isn't covered yet by existsing tests). +- [ ] If the change improves pefromance or reduces resource usage, then it would be great to add [benchmarks](https://pkg.go.dev/testing#hdr-Benchmarks) + and mention benchmark results before and after the change in the description to the pull request. + +Further checks are optional for External Contributions: + +- [ ] The change is described in **clear user-readable** form at [docs/CHANGELOG.md](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/docs/CHANGELOG.md), + since it is read by **VictoriaMetrics users** who may not know implementation details of VictoriaMetrics products. The change description must **clearly** answer the following questions: + - What does this change do? + - Why this change is needed? + The change description must link to related GitHub issues and the related docs, if any. + + Tips for writing a good changelog message: + + - Write a human-readable changelog message that describes the problem and the solution. + - Use specific text, which can be googled by users interested in the change, such as an error message, metric name, command-line flag name, etc. + - Include a link to the issue or pull request in your changelog message. + - Provide a link to the relevant documentation for any new features you add or modify. + +- [ ] After your pull request is merged, please add a message to the issue with instructions for how to test the fix or try the feature you added before the new release. + [Here is an example](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4048#issuecomment-1546453726). +- [ ] Do not close the original issue before the change is released. Please note, in some cases Github can automatically closes the issue once PR is merged. Re-open the issue in such case. +- [ ] If the change introduces a new feature, this feature must be documented in **user-readable** form at the appropriate parts of [VictoriaMetrics docs](https://docs.victoriametrics.com/). + The docs' sources are located in the [`docs` folder](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/docs). + +Examples of good changelog messages: + +1. 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). + +2. 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/).