Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs/developer: update contributing guide #111

Merged
merged 2 commits into from
Apr 4, 2024
Merged

docs/developer: update contributing guide #111

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a782d5e
docs/developer: update contributing guide
rfratto Apr 4, 2024
0a7b539
Update docs/developer/contributing.md
rfratto Apr 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 39 additions & 38 deletions docs/developer/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand All @@ -35,7 +35,7 @@ compiling and testing your changes do:
```bash
# For building:
go build .
./alloy -config.file=<config-file>
./alloy run <CONFIG_FILE>

# For testing:
make lint test # Make sure all the tests pass before you commit and push :)
Expand All @@ -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 <CONFIG_FILE>
```

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
rfratto marked this conversation as resolved.
Show resolved Hide resolved

### 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

Expand All @@ -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

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Loading