Contribution guide

docs/guides/contributing.md

@@ -0,0 +1,313 @@
+---
+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 with `make test` and add tests for your change if possible.
+- To avoid lint failures in CI it's useful to run `make common-format` and 
+  `make lint` and fix issues.
+- Commit with `git commit -s` to sign the DCO.
+- Generally, open a PRs against the repository's default branch, i.e. most often 
+  `main` or sometimes `master`. Reviewers will help with exceptions.
+- Reviewers should be assigned automatically. We aim to respond in a timely manner, 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 GitHub process, 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. Slack content is also not
+retained forever. 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 ways:
+
+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 issue 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 
+   needed. Do not work on issues labeled `triage/needs-triage` or 
+   `triage/needs-information`.
+
+## Proposal process
+
+For bigger changes and ideas we require a formal proposal and review in the 
+[Proposal repository](https://github.com/prometheus/proposals/). For details 
+please read the accepted [proposal proposal](https://github.com/prometheus/proposals/blob/main/proposals/0001-proposal-process.md).
+
+## GitHub guidelines
+
+Commit messages should describe the change made in the commit.
+We don't have strong opinions on how large or small commits should be, use your 
+best judgment to make a logical series of changes. Good commits make reviews 
+easier and thus can be merged faster. For example it's a good pattern to have a 
+commit adding a test to expose a bug and then have a separate commit to fix the 
+bug.
+Commit messages must include a `Signed-off-by: <author identity>` line. With 
+this the author agrees to the terms published at 
+https://developercertificate.org/ for _that_ particular contribution.
+
+Once you have a change you would like to propose, push it to your personal fork 
+of Prometheus and open a pull request against the default branch. The default 
+branch is usually `main` but can be `master` in some repositories.
+Some situations require a PR against a release branch, e.g. `release-3.5`. The 
+most common situations are fixes for a release candidate for a new release or a 
+fix for an LTS version of Prometheus. If in doubt, ask via one of the channels 
+mentioned in this document.
+
+The needed reviewers will be added automatically. Anyone else that should or 
+wants to review a change can be mentioned by their user name in a comment, but 
+please avoid pinging random community members.
+
+We have checks that run on every PR. To merge, all checks should succeed. Any 
+failing checks should be investigated and addressed by the PR author.
+
+Reviewers might request changes. It is common practice for PRs to evolve with 
+additional fixup commits during review. Reviewers may squash these into a 
+coherent set of commits when merging, but should ensure the final commit 
+messages are meaningful and not auto-generated. Alternatively, reviewers may 
+ask the author to group commits into something reasonable before merging. 
+Rebasing a branch for a pull request is generally fine. Only once others have 
+changes based on commits that are not part of the `main` branch yet, commit 
+authors should refrain from rewriting those commits. If a PR becomes too large 
+or mixes unrelated concerns (e.g. refactoring and logic changes), consider 
+splitting it into separate PRs to make review easier.
+
+## AI generated contributions
+
+The Prometheus authors don't discourage the use of AI tools to generate code.
+However we require a [DCO](https://developercertificate.org/) on each commit, by 
+which the author certifies that the contribution was created in whole or in part 
+by the author and that they have the right to submit it. Or if the contribution 
+is based upon previous work, it is covered under an appropriate open source 
+license and the author has the right under that license to submit that work with 
+modifications. See https://www.linuxfoundation.org/legal/generative-ai for more 
+details.
+The human author must fully understand the code they are submitting. Please 
+consider the DCO and carefully review AI-generated code before submitting 
+it. We encourage explicitly disclosing AI tool usage, for example by adding an 
+`Assisted-by: <name of AI tool used>` to the respective commits.
+
+For discussions around issues and PRs we strongly prefer a dialog with humans.
+
+## Coding style
+
+Much has been written about coding styles for a given language elsewhere. For 
+Prometheus contributions stick to the following:
+
+- Use idiomatic code of the language.
+- Stick to the existing style around you. Don’t conflate style improvements with 
+  code changes.
+- We have plenty of linters, use `make format`, `make lint` and `make style` to 
+  correctly format your code.
+- Use proper English grammar and punctuation. Don’t needlessly abbreviate.
+  - BAD: `// batchQueue full, try again later`
+  - GOOD: `// The batchQueue is full, so we need to try again later.`
+- In Markdown, limit line length to 80 characters, instead of one line per 
+  paragraph, unless the line ends in a URL. It makes commenting in reviews so 
+  much easier.
+
+
+### Go style guide
+
+Go is the main programming language used in Prometheus and its ecosystem. Go 
+based projects tend to follow a very similar style, Prometheus is no exception.  
+https://go.dev/wiki/CodeReviewComments is a great resource for specifics. We 
+have a few rules on top of that worth mentioning here:
+
+- Often we put named imports into a separate block. The blocks should be grouped 
+  into stdlib / other repos / same repo.
+- Doc comments on exported types are not enforced by the linter (because of too 
+  many false positives), but we do care. Use them where they make sense.
+- Break long function signatures into multiple lines in the following way:
+  End the first line with the opening parenthesis, then put the function
+  parameters on any number of lines as you see fit, followed by a separate
+  line beginning with the closing parenthesis. For example:
+```go
+func (s *shards) sendSamples(
+	ctx context.Context, samples []prompb.TimeSeries,
+	sampleCount, exemplarCount, histogramCount int,
+	pBuf *proto.Buffer, buf compression.EncodeBuffer, compr compression.Type,
+) error {
+```
+**NOT**
+```go
+func (s *shards) sendSamples(ctx context.Context, samples []prompb.TimeSeries,
+	sampleCount, exemplarCount, histogramCount int,
+	pBuf *proto.Buffer, buf compression.EncodeBuffer, compr compression.Type) error {
+```
+**OR**
+```go
+func (s *shards) sendSamples(
+    ctx context.Context, samples []prompb.TimeSeries,
+	sampleCount, exemplarCount, histogramCount int,
+	pBuf *proto.Buffer, buf compression.EncodeBuffer, compr compression.Type) error {
+
+## Developer summit details
+
+Developer summits usually happen on the last Thursday each month as an online
+meeting. See the [Prometheus
+calendar](https://calendar.google.com/calendar/u/0/embed?src=prometheus.io_bdf9qgm081nrd0fe32g3olsld0%40group.calendar.google.com)
+for the current schedule. In addition, we aim for all-day in-person summits
+whenever enough active Prometheus developers are gathered at one place for some
+reason, typically at a conference like [PromCon](https://promcon.io/) or
+[Kubecon EU](https://events.linuxfoundation.org/kubecon-cloudnativecon-europe/).
+
+The online meetings are open for everyone, while the in-person meetings might
+have some restrictions for logistical reasons. If in doubt, ask via the channels
+listed above, and we'll see what can be done. We also try to make in-person
+summits accessible for online participants on a best-effort basis.
+
+The Prometheus team curates the agenda based on recent discussions via other
+channels. You can propose a topic explicitly by adding it at the top of the
+meeting notes (see below) or by sending a mail to the [developer mailing
+list](https://groups.google.com/forum/#!forum/prometheus-developers) at least
+24 hours prior to the summit.
+
+### Meeting notes
+
+We maintain [rolling meeting notes
+document](https://docs.google.com/document/d/1uurQCi5iVufhYHGlBZ8mJMK_freDFKPG0iYBQqJ9fvA) (current version starting 2024-09-13).
+
+Historical meeting notes:
+
+- [2017 developer summit notes](https://docs.google.com/document/d/1DaHFao0saZ3MDt9yuuxLaCQg8WGadO8s44i3cxSARcM)
+- [2018 developer summit notes](https://docs.google.com/document/d/1-C5PycocOZEVIPrmM1hn8fBelShqtqiAmFptoG4yK70)
+- [2019 developer summit notes](https://docs.google.com/document/d/1NQIX78nwBhfLZD3pAb0PK-uBKYqnkzjjVhOQ-kIaEGU)
+- [2019 developer summit 2 notes](https://docs.google.com/document/d/1VVxx9DzpJPDgOZpZ5TtSHBRPuG5Fr3Vr6EFh8XuUpgs)
+- [2020 virtual developer summit 1 notes](https://docs.google.com/document/d/1yuaPKLDvhJNXMF1ubsOOm5kE2_6dvCxHowBQIDs0KdU)
+- [2020 virtual developer summit 2 notes](https://docs.google.com/document/d/1vhXKpCNY0k2cbm0g10uM2msXoMoH8CTwrg_dyqsFUKo)
+- [2020 virtual developer summit 3 notes](https://docs.google.com/document/d/18Jbl5LC_FPLqCqU12qY8XpjVMJLCtGt-ykbyAhYXcIc)
+- [2020 virtual developer summit 4 notes](https://docs.google.com/document/d/1_60pplXWF1R-utJtswJYFf8F9HBAJdDS5x4Lv9CgAJ8)
+- [2020 virtual developer summit 5 notes](https://docs.google.com/document/d/1iO1QHRyABaIpc6xXB1oqu91jYL1QQibEpvQqXfQF-WA)
+- [2021 virtual developer summit 1 notes](https://docs.google.com/document/d/10o4gkjgK46MdUHTowpUG_pyeON3Z5k0CbPBqQ211KOE)
+- [2021-2024 developer summit rolling notes](https://docs.google.com/document/d/11LC3wJcVk00l8w5P3oLQ-m3Y37iom6INAMEu2ZAGIIE)
+
+### Facilitator
+
+The Facilitator role was created to help the Prometheus team to run the
+Developer Summits effectively. It's a rotational role (switches for
+every meeting) and its responsibilities are spread across different
+phases of the summit:
+
+#### Before the summit
+
+Before the summit, the Facilitator's main goal is to help the
+Prometheus team define the agenda and the topics to be discussed while
+making sure interested parties of the most voted topics will be able to
+attend the summit. We suggest the following tasks:
+
+- Two or three days before the meeting, send reminders in our public
+  community channels inviting people to add Agenda Topics, and
+  Prometheus Team members and maintainers to vote on topics they'd
+  like to discuss.
+- One day before the meeting, reach out to "Topic owners" who
+  received the most votes to make sure they'll make it to the summit.
+
+#### During the summit
+
+During the summit, the Facilitator is there to make sure that the meeting runs
+smoothly, and that consensus is reached when needed. We suggest the
+following tasks:
+
+- Start the meeting on time. Use `@prometheus.io` account for the admin meeting
+  permissions.
+- Start the recording and mention that the Code of Conduct applies.
+- Select topics to be discussed based on votes and who is currently present in
+  the meeting.
+- Take notes or find volunteer for taking notes in the shared document.
+- Strategically step in when the discussion is not moving forward or deviating
+  from the topic.
+- Call for consensus when needed.
+
+#### After the summit
+
+Once the meeting is over, the last task of the Facilitator is to find a new
+Facilitator for the next summit by sending an email to the Prometheus Team
+mailing list.