From fcde8a7cc106ff30ca3a34c34fb694e611381cff Mon Sep 17 00:00:00 2001 From: Robert Fratto Date: Thu, 4 Apr 2024 10:24:29 -0400 Subject: [PATCH] docs/developer: update contributing guide (#111) --- docs/developer/contributing.md | 77 +++++++++++++++++----------------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/docs/developer/contributing.md b/docs/developer/contributing.md index 2ba0a3b8b5..110ba372bd 100644 --- a/docs/developer/contributing.md +++ b/docs/developer/contributing.md @@ -1,13 +1,13 @@ # Contributing -Grafana Agent uses GitHub to manage reviews of pull requests. +Grafana Alloy uses GitHub to manage reviews of pull requests. If you're planning to do a large amount of work, you should discuss your ideas -in an [issue][new-issue] or an [RFC][]. This will help you avoid unnecessary -work and surely give you and us a good deal of inspiration. +in an [issue][new-issue]. This will help you avoid unnecessary work and surely +give you and us a good deal of inspiration. -Pull requests can be opened immediately without an issue for trivial fixes or -improvements. +For trivial fixes or improvements, pull requests can be opened immediately +without an issue. ## Before Contributing @@ -26,7 +26,7 @@ from contributors on the same issue. Please check the [`good first issue`][good-first-issue] label to find issues that are good for getting started. If you have questions about one of the issues, with or without the tag, please comment on them and one of the -maintainers will clarify it. For a quicker response, contact us in the #agent +maintainers will clarify it. For a quicker response, contact us in the `#alloy` channel in our [community Slack][community-slack]. See next section for detailed instructions to compile the project. For quickly @@ -35,7 +35,7 @@ compiling and testing your changes do: ```bash # For building: go build . -./alloy -config.file= +./alloy run # For testing: make lint test # Make sure all the tests pass before you commit and push :) @@ -51,47 +51,49 @@ needs to be disregarded or is a false-positive, you can add a special comment All our issues are regularly tagged with labels so that you can also filter down the issues involving the components you want to work on. -## Compiling the Agent +## Compiling Alloy -To build Grafana Agent from source code, please install the following tools: +To build Alloy from source code, please install the following tools: 1. [Git](https://git-scm.com/) -2. [Go](https://golang.org/) (version 1.19 and up) +2. [Go](https://golang.org/) (see `go.mod` for what version of Go is required) 3. [Make](https://www.gnu.org/software/make/) 4. [Docker](https://www.docker.com/) -You can directly use the go tool to download and install the agent binary into your GOPATH: +> **NOTE**: `go install` cannot be used to install Alloy due to `replace` +> directives in our `go.mod` file. - $ GO111MODULE=on go install github.com/grafana/alloy - $ alloy run your_config.river +To compile Alloy, clone the repository and build using `make alloy`: + +```bash +$ git clone https://github.com/grafana/alloy.git +$ cd alloy +$ make alloy +$ ./build/alloy run +``` An example of the above configuration file can be found [here][example-config]. -You can also clone the repository yourself and build using `make agent`: +Run `make help` for a description of all available Make targets. - $ mkdir -p $GOPATH/src/github.com/grafana - $ cd $GOPATH/src/github.com/grafana - $ git clone https://github.com/grafana/alloy.git - $ cd agent - $ make agent - $ ./build/alloy run your_config.river +### Compile on Linux -The Makefile provides several targets: +Compiling Alloy on Linux requires extra dependencies: -* `agent`: build the agent binary -* `test`: run the tests -* `lint`: run linting checks +* [systemd headers](https://packages.debian.org/sid/libsystemd-dev) for Promtail -### Compile on Linux -Compiling Grafana Agent on Linux requires extra dependencies: + * Can be installed on Debian-based distributions with: -* [systemd headers](https://packages.debian.org/sid/libsystemd-dev) for Promtail - * Can be installed on Debian-based distributions with: ```sudo apt-get install libsystemd-dev``` + ```bash + sudo apt-get install libsystemd-dev + ``` ### Compile on Windows -Compiling Grafana Agent on Windows requires extra dependencies: -* [tdm-gcc](https://jmeubank.github.io/tdm-gcc/download/) full 64 bit install for cgo compiliation. +Compiling Alloy on Windows requires extra dependencies: + +* [tdm-gcc](https://jmeubank.github.io/tdm-gcc/download/) full 64-bit install + for compiling C dependencies. ## Pull Request Checklist @@ -101,15 +103,15 @@ that may have appeared during development. PRs should not introduce regressions or introduce any critical bugs. If your PR isn't covered by existing tests, some tests should be added to validate the new -code (note that 100% code coverage is _not_ a requirement). Smaller PRs are -more likely to be reviewed faster and easier to validate for correctness; -consider splitting up your work across multiple PRs if making a significant +code (100% code coverage is _not_ a requirement). Smaller PRs are more likely +to be reviewed faster and easier to validate for correctness; consider +splitting up your work across multiple PRs if making a significant contribution. If your PR is not getting reviewed or you need a specific person to review it, you can @-reply a reviewer asking for a review in the pull request or a comment, or you can ask for a review on the Slack channel -[#agent](https://slack.grafana.com). +[#alloy](https://slack.grafana.com). ## Updating the changelog @@ -161,8 +163,8 @@ For example: ## Dependency management -The Grafana Agent project uses [Go modules][go-modules] to manage dependencies -on external packages. +Alloy uses [Go modules][go-modules] to manage dependencies on external +packages. To add or update a new dependency, use the `go get` command: @@ -198,12 +200,11 @@ If upstream is unresponsive, consider choosing a different dependency or making a hard fork (i.e., creating a new Go module with the same source). [new-issue]: https://github.com/grafana/alloy/issues/new -[RFC]: ../rfcs/0001-designing-in-the-open.md [code-review-comments]: https://code.google.com/p/go-wiki/wiki/CodeReviewComments [best-practices]: https://peter.bourgon.org/go-in-production/#formatting-and-style [uber-style-guide]: https://github.com/uber-go/guide/blob/master/style.md [CLA]: https://cla-assistant.io/grafana/alloy [good-first-issue]: https://github.com/grafana/alloy/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22 [community-slack]: https://slack.grafana.com/ -[example-config]: ../../example-config.river +[example-config]: ../../example-config.alloy [go-modules]: https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more