github.com/grafana/pyroscope@v1.18.0/docs/internal/contributing/README.md (about)

     1  # Contributing
     2  
     3  Welcome! We're excited that you're interested in contributing. Below are some basic guidelines.
     4  
     5  ## Workflow
     6  
     7  Grafana Pyroscope follows a standard GitHub pull request workflow. If you're unfamiliar with this workflow, read the very helpful [Understanding the GitHub flow](https://guides.github.com/introduction/flow/) guide from GitHub.
     8  
     9  You are welcome to create draft PRs at any stage of readiness - this
    10  can be helpful to ask for assistance or to develop an idea. But before
    11  a piece of work is finished it should:
    12  
    13  - Be organised into one or more commits, each of which has a commit message that describes all changes made in that commit ('why' more than 'what' - we can read the diffs to see the code that changed).
    14  - Each commit should build towards the whole - don't leave in back-tracks and mistakes that you later corrected.
    15  - Have unit for new functionality or tests that would have caught the bug being fixed.
    16  - If you have made any changes to flags, configs and/or protobuf definitions, run `make generate` and commit the changed files.
    17  
    18  ## Requirement
    19  
    20  To be able to run make targets you'll need to install:
    21  
    22  - [Go](https://go.dev/doc/install) (>= 1.24)
    23  - [Docker](https://docs.docker.com/engine/install/)
    24  
    25  All other required tools will be automatically downloaded `$(pwd)/.tmp/bin`.
    26  
    27  > If you need a new CLI, we recommend you follow the same pattern and downloads requirement from the makefile.
    28  
    29  ## Formatting
    30  
    31  Grafana Pyroscope uses [`golang-ci-lint`](https://github.com/golangci/golangci-lint) tool to format the Go files, and sort imports.
    32  We use goimports with `-local github.com/grafana/pyroscope` parameter, to put Grafana Pyroscope internal imports into a separate group. We try to keep imports sorted into three groups: imports from standard library, imports of 3rd party packages and internal Grafana Pyroscope imports. Goimports will fix the order, but will keep existing newlines between imports in the groups. Avoid introducing newlines there.
    33  
    34  Use `make lint` to ensure formatting is correct.
    35  
    36  ## Building Grafana Pyroscope
    37  
    38  To build:
    39  
    40  ```
    41  make go/bin
    42  ```
    43  
    44  To run the unit test suite:
    45  
    46  ```
    47  make go/test
    48  ```
    49  
    50  To build the docker image use:
    51  
    52  ```
    53  make docker-image/pyroscope/build
    54  ```
    55  
    56  This target uses the `go/bin` target to first build binaries to include in the image.
    57  Make sure to pass the correct `GOOS` and `GOARCH` env variables.
    58  
    59  #### amd64 builds
    60  ```
    61  make GOOS=linux GOARCH=amd64 docker-image/pyroscope/build
    62  ```
    63  
    64  #### arm64 builds
    65  ```
    66  make IMAGE_PLATFORM=linux/arm64 GOOS=linux GOARCH=arm64 docker-image/pyroscope/build
    67  ```
    68  
    69  #### Running examples locally
    70  replace `image: grafana/pyroscope` with the local tag name you got from docker-image/pyroscope/build (i.e):
    71  
    72  ```
    73    pyroscope:
    74      image: grafana/pyroscope:main-470125e1-WIP
    75      ports:
    76        - '4040:4040'
    77  ```
    78  
    79  #### Run with Pyroscope with embedded Grafana + Profiles Drilldown
    80  
    81  To quickly test the whole stack it is possible to run an embedded Grafana by using the target parameter:
    82  
    83  ```
    84  go run ./cmd/pyroscope --target all,embedded-grafana
    85  ```
    86  
    87  This will Pyroscope on `:4040` and the embedded Grafana on port `:4041`.
    88  
    89  #### Frontend development
    90  
    91  The frontend application is not in active development. While the UI it provides is usable and stable,
    92  the recommended way to view and analyze profiling data is to use the 
    93  [Profiles Drilldown](https://grafana.com/docs/grafana/latest/visualizations/simplified-exploration/profiles/) Grafana app (pre-installed in recent Grafana versions).
    94  
    95  If you do need to make changes to the frontend code, the following instructions should get you started.
    96  
    97  **Versions for development tools**:
    98  - Node v18
    99  - Yarn v1.22
   100  
   101  The frontend code is located in the `public/app` directory, although its `package.json` file is at the repository root.
   102  
   103  To run the local frontend application in development mode:
   104  
   105  ```sh
   106  yarn install
   107  yarn dev
   108  ```
   109  
   110  This will:
   111  - install and update frontend dependencies
   112  - launch a process that will build the frontend code
   113  - serve the built app at `http://localhost:4041`
   114  - keep the web app updated any time you update the frontend source code
   115  
   116  The web app will not initially be connected to a Pyroscope server, so all attempts to fetch data will fail.
   117  
   118  To launch a pyroscope server for development purposes:
   119  ```sh
   120  yarn backend:dev
   121  ```
   122  
   123  This yarn script actually runs the following:
   124  ```sh
   125  make build run 'PARAMS=--config.file ./cmd/pyroscope/pyroscope.yaml'
   126  ```
   127  
   128  It can take a while for this process to build and start serving pyroscope data, but
   129  once it is fully active, the pyroscope web app service at `http://localhost:4041`
   130  will be able to interact with it.
   131  
   132  ### Dependency management
   133  
   134  We use [Go modules](https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more) to manage dependencies on external packages.
   135  However, we don't commit the `vendor/` folder.
   136  
   137  To add or update a new dependency, use the `go get` command:
   138  
   139  ```bash
   140  # Pick the latest tagged release.
   141  go get example.com/some/module/pkg
   142  
   143  # Pick a specific version.
   144  go get example.com/some/module/pkg@vX.Y.Z
   145  ```
   146  
   147  Tidy up the `go.mod` and `go.sum` files:
   148  
   149  ```bash
   150  make go/mod
   151  ```
   152  
   153  Commit the changes to `go.mod` and `go.sum` before submitting your pull request.
   154  
   155  ## Documentation
   156  
   157  The Grafana Pyroscope documentation is compiled into a website published at [grafana.com](https://grafana.com/).
   158  
   159  To start the website locally you can use `make docs/docs`. The command will print instructions on how to access the website.
   160  
   161  Note: if you attempt to view pages on GitHub, it's likely that you might find broken links or pages. That is expected and should not be addressed unless it is causing issues with the site that occur as part of the build.