diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md new file mode 100644 index 000000000..f26ddd804 --- /dev/null +++ b/docs/guides/contributing.md @@ -0,0 +1,301 @@ +--- +title: Contributing +--- + +# Contributor's guide + +This document provides general guidelines for contributors of all experience +levels. + +If you are new, you might want to check out [how to pick something to +work on](#how-to-pick-something-to-work-on) first. + +If you are an experienced contributor Looking to contribute a change, check the +[high level process](#how-to-get-a-pr-merged). + +If you have concrete plans for something more involved already, please refer to the [proposal +process](#proposal-process). + +This document is guide for the prometheus/prometheus repository. Much of this +applies to other repos in the Prometheus community, but these projects might +have their own guides and rules. For repository-specific information, check out +the README.md and CONTRIBUTING.md files of each repository. + +## How to get a PR merged + +If you’re working on your first contribution please read this whole document, this section is aimed at experienced Open Source contributors. + +- Test changes locally and consider adding tests for your change. +- Commit with `git commit -s` to sign the DCO. +- Generally, open a PRs against the repositories default branch, i.e. most often + `main` or sometimes `master`. Reviewers will help with exceptions. +- Reviewers should be assigned automatically, we aim to respond timely but other + priorities can create delays. +- Check the results of failing CI jobs, all are expected to succeed. +- Reviewers might request changes. Addressing these quickly will improve the + turn-around time of the PR. + +For more details around our git refer to +[the Github Guidelines](#github-guidelines). + +## Communication channels + +The usual [community channels for users](/community) are meant to discuss usage +of Prometheus including using Prometheus code for non-Prometheus development +(e.g. instrumenting code with a Prometheus instrumentation library). +Development of Prometheus components themselves happens via other channels as +described in this section. + +### GitHub + +Contributions are reviewed in GitHub pull requests. See the [GitHub +guidelines](github-guidelines) below for details. GitHub issues are often a +good way to discuss specific bugs and feature requests. For informal or +overarching discussions, the other channels below might be more appropriate. + +### CNCF Slack + +A lot of the informal chat-like discussion happens on the [CNCF +Slack](https://slack.cncf.io/). The main development channel is +`#prometheus-dev`, but there are plenty of specialized channels. Look for +channel names like `#prometheus-...-dev`, e.g. `#prometheus-protobuf-dev`. + +Note that Slack is a silo. The content is not indexed by external search +engines, there is no easy way to export and archive the content, and even +read-only access requires a login. Therefore, consider everything in Slack as +ephemeral and inaccessible for the general public. Important information, like +the result of a discussion, should also be published via other channels (e.g. +on [GitHub](github) or the [mailing list](#developer-mailing-list)) to make it +accessible and durable. Avoid linking to Slack messages from other media +without summarizing the content of the linked messages. + +### Developer mailing list + +The +[prometheus-developers](https://groups.google.com/forum/#!forum/prometheus-developers) +mailing list +([mirror](https://www.mail-archive.com/prometheus-developers@googlegroups.com/)) +is suitable for announcements and more formal discussions about overarching +topics. The mailing list archive is indexed by search engines and thus a good +way to find past discussions and ensure that information is not lost in a silo +like Slack. + +### Developer summits + +Developer summits are public meetings to discuss more involved development +topics. For the schedule, meeting notes, and many other details see the +[dedicated section](#developer-summit-details) below. + +### Work groups + +If developers working on a specific topic would like to conduct online meetings +on a more or less regular basis, they start a work group. Work group meetings +are public and published via the [Prometheus +calendar](https://calendar.google.com/calendar/u/0/embed?src=prometheus.io_bdf9qgm081nrd0fe32g3olsld0%40group.calendar.google.com). + +## How to pick something to work on + +The best feature or bug to work on is something that matters to you. Something +you are already a user or even expert on or something you want to become an +expert on. + +The Prometheus community tries to help with identifying good issues to work on +in two way: + +1. Look for the label `good-first-issue`. This label identifies work that we + think would be a good starting point for any new contributors. +2. If you are looking for more complex issues to solve look for the + `triage/accepted` label. This label indicates that an issues has been + triaged, all needed information has been gathered and work can begin. + The labels `triage/needs-triage` and `triage/needs-information` mean that + either no one has had time to look at the issue yet or more information is + need. Do not work on issues labeled `triage/needs-triage` or + `triage/needs-information` .See