Grafana Agent 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 or an RFC. 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.
- Review the following code coding style guidelines:
- Go Code Review Comments
- The Formatting and style section of Peter Bourgon's Go: Best Practices for Production Environments
- The Uber Go Style Guide
- Sign our CLA, otherwise we're not able to accept contributions.
Should you wish to work on an issue, please claim it first by commenting on the GitHub issue that you want to work on it. This is to prevent duplicated efforts from contributors on the same issue.
Please check the 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
channel in our community Slack.
See next section for detailed instructions to compile the project. For quickly compiling and testing your changes do:
# For building:
go build ./cmd/grafana-agent/
./grafana-agent -config.file=<config-file>
# For testing:
make lint test # Make sure all the tests pass before you commit and push :)We use golangci-lint for linting
the code.
As a last resort, if linting reports an issue and you think that the warning
needs to be disregarded or is a false-positive, you can add a special comment
//nolint:linter1[,linter2,...] before the offending line.
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.
To build Grafana Agent from source code, please install the following tools:
You can directly use the go tool to download and install the agent binary into your GOPATH:
$ GO111MODULE=on go install github.com/grafana/agent/cmd/grafana-agent
$ grafana-agent -config.file=your_config.yml
An example of the above configuration file can be found here.
You can also clone the repository yourself and build using make agent:
$ mkdir -p $GOPATH/src/github.com/grafana
$ cd $GOPATH/src/github.com/grafana
$ git clone https://github.com/grafana/agent.git
$ cd agent
$ make agent
$ ./build/grafana-agent -config.file=your_config.yml
The Makefile provides several targets:
agent: build the agent binarytest: run the testslint: run linting checks
Compiling Grafana Agent on Linux requires extra dependencies:
- systemd headers for Promtail
- Can be installed on Debian-based distributions with:
sudo apt-get install libsystemd-dev
- Can be installed on Debian-based distributions with:
Compiling Grafana Agent on Windows requires extra dependencies:
- tdm-gcc full 64 bit install for cgo compiliation.
Changes should be branched off of the main branch. It's recommended to rebase
on top of main before submitting the pull request to fix any merge conflicts
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 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.
We keep a changelog of code changes which result in new or changed user-facing behavior.
Changes are grouped by change type, denoted by ### Category_Name. The change
types are, in order:
- Security fixes
- Breaking changes
- Deprecations
- Features
- Enhancements
- Bugfixes
- Other changes
Categories won't be listed if there's not any changes for that category.
When opening a PR which impacts user-facing behavior, contributors should:
-
Determine which changes need to be documented in the changelog (a PR may change more than one user-facing behavior).
-
If there are no other changes for that change type, add a header for it (e.g.,
### Bugfixes). Make sure to keep the order listed above. -
Add relevant entries into the changelog.
When in doubt, look at a previous release for style and ordering examples.
Change entries in the changelog should:
- Be complete sentences, ending in a period. It is acceptable to use multiple complete sentences if one sentence can't accurately describe the change.
- Describe the impact on the user which is reading the changelog.
- Include credit to the GitHub user that opened the PR following the sentence.
For example:
- Config file reading is now 1500% faster. (@torvalds)
Readers should be able to understand how a change impacts them. Default to being explicit over vague.
- Vague:
- Fixed issue with metric names. (@ghost)- Explicit:
- Fixed issue where instances of the letter s in metric names were replaced with z. (@ghost)
The Grafana Agent project uses Go modules to manage dependencies on external packages.
To add or update a new dependency, use the go get command:
# Pick the latest tagged release.
go get example.com/some/module/pkg@latest
# Pick a specific version.
go get example.com/some/module/pkg@vX.Y.ZTidy up the go.mod and go.sum files:
go mod tidyYou have to commit the changes to go.mod and go.sum before submitting the
pull request.
Using a fork to pull in custom changes must always be temporary.
PRs which add replace directives in go.mod to change a module to point to a
fork will only be accepted once an upstream PR is opened to officially move the
changes to the official module.
Contributors are expected to work with upstream to make their changes
acceptable, and remove the replace directive as soon as possible.
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).