# Contributing to OpenTelemetry Demo Webstore

Welcome to the OpenTelemetry Demo repository! We appreciate your interest in
contributing. Whether you're fixing a bug, improving documentation, or adding a
new feature, we value your contribution.

Before getting started, please review the
[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/guides/contributor/README.md)
for details on code attribution and best practices.

## Getting Started

### Join a SIG Call

We meet every other Wednesday at 8:00 PT. The schedule may change based on
contributors' availability. Check the [OpenTelemetry Community Calendar](https://github.com/open-telemetry/community?tab=readme-ov-file#special-interest-groups)
for specific dates and Zoom links.

The call is open to all. Whether you're a seasoned OpenTelemetry developer,
just starting your journey, or simply curious about the work we do, you're more
than welcome to participate.

See the
[public meeting notes](https://docs.google.com/document/d/16f-JOjKzLgWxULRxY8TmpM_FjlI1sthvKurnqFz9x98/edit)
for a summary description of past meetings.
For edit access, ask in our
[Slack channel](https://cloud-native.slack.com/archives/C03B4CWV4DA).
If you are new to the CNCF Slack community, you can [create an
account](https://slack.cncf.io/).

### Sign the Contributor License Agreement (CLA)

Before contributing, sign the [CLA](https://identity.linuxfoundation.org/projects/cncf)

### Find a Mentor (Buddy System)

New to OpenTelemetry? We encourage you to find a mentor who can guide you
through your first contribution.

1. Create your [CNCF Slack account](https://slack.cncf.io/) and join the
   [otel-community-demo](https://app.slack.com/client/T08PSQ7BQ/C03B4CWV4DA)
   channel.
2. Post in the room with an introduction to yourself, what area you are
   interested in (check issues marked with [help
   wanted](https://github.com/open-telemetry/opentelemetry-demo/labels/help%20wanted)),
   and say you are looking for a buddy. We will match you with someone who has
   experience in that area.

Your OpenTelemetry buddy is your resource to talk to directly on all aspects of
contributing to OpenTelemetry: providing context, reviewing PRs, and helping
those get merged. Buddies will not be available 24/7, but is committed to
responding during their normal contribution hours.

## Setting Up Your Development Environment

### Prerequisites

Ensure you have the following installed:

- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Make](https://www.gnu.org/software/make/)
- [Docker][docker] with [Docker Compose][docker-compose] v2.0.0+

Alternatively, [Podman][podman] 4.7.0+ can be used instead of Docker. See
[Using Podman Instead of Docker](#using-podman-instead-of-docker) for setup
instructions.

[docker]: https://www.docker.com/get-started/
[docker-compose]: https://docs.docker.com/compose/install/#install-compose
[podman]: https://podman.io/getting-started/installation

### Clone the Repository

```sh
git clone https://github.com/open-telemetry/opentelemetry-demo.git
cd opentelemetry-demo/
```

### Run the Demo

```sh
make start
```

### Using Podman Instead of Docker

The demo supports both Docker and Podman. Docker is the default container
runtime. To use Podman instead, first set the `DOCKER_SOCK` to use podman,
in `.env.override` uncomment `# DOCKER_SOCK=/run/user/1000/podman/podman.sock`
This is needed for the otel-collector to work correctly. For example, you should
have:

```sh
# Rootless podman: use the podman Docker-compatible API socket so the collector's
# docker resource detector and docker_stats receiver can connect.
DOCKER_SOCK=/run/user/1000/podman/podman.sock
```

Next you can run podman with:

```sh
DOCKER_COMPOSE_CMD="podman compose" make start
```

To persist this setting, add it to your shell profile (e.g., `~/.bashrc`):

```sh
export DOCKER_CMD=podman
export DOCKER_COMPOSE_CMD="podman compose"
```

Then you can simply run `make start` and it will use Podman.

#### Podman-specific Notes

- Podman runs rootless by default, which may require adjusting some
  system settings
- If you encounter permission issues, ensure your user is in the
  appropriate groups
- Ensure the Podman socket is running: `systemctl --user start podman.socket`
- You can check the Podman socket status with: `systemctl --user status podman.socket`

### Verify the Webstore & Telemetry

Once the images are built and containers are started, visit:

- **Webstore**: [http://localhost:8080/](http://localhost:8080/)
- **Jaeger**: [http://localhost:8080/jaeger/ui/](http://localhost:8080/jaeger/ui/)
- **Grafana**: [http://localhost:8080/grafana/](http://localhost:8080/grafana/)
- **OpAMP**: [http://localhost:8080/opamp/](http://localhost:8080/opamp/)
- **Feature Flags UI**: [http://localhost:8080/feature/](http://localhost:8080/feature/)
- **Load Generator UI**: [http://localhost:8080/loadgen/](http://localhost:8080/loadgen/)

The OpAMP UI shows the OpenTelemetry Collector as a managed agent. Click the
collector instance ID to view its health status, version, attributes, and
effective configuration.

## Troubleshooting Common Issues

### Docker Not Running

**Error:** `Error response from daemon: Docker daemon is not running.`

**Solution:**

- **Windows/macOS**: Open Docker Desktop and ensure it's running.
- **Linux**: Check Docker status:

```sh
systemctl status docker
```

If inactive, start it:

```sh
sudo systemctl start docker
```

### Podman Not Running or Socket Issues

**Error:** `Cannot connect to Podman` or socket-related errors

**Solution:**

- Ensure the Podman socket is running:

```sh
systemctl --user start podman.socket
```

- Verify the socket is active:

```sh
systemctl --user status podman.socket
```

- Verify the socket exists:

```sh
podman info --format '{{.Host.RemoteSocket.Path}}'
```

- If using rootless Podman, ensure `XDG_RUNTIME_DIR` is set correctly.

### Gradle Issues (Windows)

If you encounter Gradle issues, run:

```sh
cd src/ad/
./gradlew installDist
./gradlew wrapper --gradle-version 7.4.2
```

### Build Cache Issues

While developing, you may encounter issues with container build cache.
To clear the cache:

```sh
docker system prune -a   # For Docker
podman system prune -a   # For Podman
```

Warning: This removes all unused container data, including images, containers,
volumes, and networks. Use with caution.

### Debugging Tips

- Check running containers:

```sh
docker ps       # For Docker
podman ps       # For Podman
```

- View logs for services:

```sh
docker logs <container_id>   # For Docker
podman logs <container_id>   # For Podman
```

- Restart containers if needed:

```sh
make restart service=<service-name>
```

### Review the Documentation

The Demo team is committed to keeping the demo up to date. That means the
documentation as well as the code. When making changes to any service or feature
remember to find the related docs and update those as well. Most (but not all)
documentation can be found on the OTel website under [Demo docs][docs].

### Running the React Native example

If you are interested in running the React Native example app in this repo
please review [these instructions](src/react-native-app/README.md).

## Create Your First Pull Request

### How to Send Pull Requests

Everyone is welcome to contribute code to `opentelemetry-demo` via
GitHub pull requests (PRs).

To create a new PR, fork the project in GitHub and clone the upstream repo:

> [!NOTE]
> Please fork to a personal GitHub account rather than a corporate/enterprise
> one so maintainers can push commits to your branch.
> **Pull requests from protected forks will not be accepted.**

```sh
git clone https://github.com/open-telemetry/opentelemetry-demo.git
```

Navigate to the repo root:

```sh
cd opentelemetry-demo
```

Add your fork as an origin:

```sh
git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-demo.git
```

Check out a new branch, make modifications and push the branch to your fork:

```sh
$ git checkout -b feature
# change files
$ git add my/changed/files
$ git commit -m "short description of the change"
$ git push fork feature
```

Test your changes locally before opening a PR. For a change that affects one
service, rebuild and restart only that service:

```sh
make build service=<service-name>
make restart service=<service-name>
```

For example, if you change the Shipping service:

```sh
make build service=shipping
make restart service=shipping
```

If the demo is not already running, or your change affects shared Docker Compose
configuration, environment variables, generated protobufs, cross-service
contracts, or collector/frontend-proxy configuration, start the demo stack after
building the affected service:

```sh
make build service=<service-name>
make start
```

Verify the change using the path that matches what you changed: the Webstore UI,
direct service endpoints, container logs, Jaeger traces, Grafana dashboards, or
other telemetry views as appropriate.

Update the relevant [documentation][docs] before opening the PR for user-visible
behavior, telemetry, configuration, or workflow changes.

#### Adding a changelog entry

The `CHANGELOG.md` is generated from individual fragment files under
[`.chloggen`](./.chloggen), one per pull request, using
[chloggen](https://github.com/open-telemetry/opentelemetry-go-build-tools/tree/main/chloggen).
Because each PR adds its own file instead of editing a shared section, changelog
merge conflicts are avoided.

For any user-visible behavior, telemetry, configuration, or workflow change:

1. Create a fragment for your branch: `make chlog-new`. This copies
   [`.chloggen/TEMPLATE.yaml`](./.chloggen/TEMPLATE.yaml) to
   `.chloggen/<your-branch>.yaml`.
2. Fill in `change_type`, `component`, `note`, and `issues` (use your PR number
   if there is no separate issue).
3. Validate it: `make chlog-validate`. You can preview the rendered changelog
   with `make chlog-preview`.
4. Commit the fragment as part of your PR.

Trivial typo, cosmetic, and purely internal cleanup changes may not need a
changelog entry. If your PR does not require one, add the `Skip Changelog` label
to indicate the omission is intentional.

#### How fragments become the changelog at release time

The fragments that accumulate in `.chloggen/` between releases are the
"unreleased" changelog. During a release a maintainer runs
`make chlog-update VERSION=x.x.x` (see [Making a new release](#making-a-new-release)),
which collects every fragment, groups the entries by `change_type`, inserts a
new `## x.x.x` section into `CHANGELOG.md` directly below the
`<!-- next version -->` marker, and then deletes the consumed fragment files
(leaving `TEMPLATE.yaml`). The marker stays in place for the next cycle.

Within the new version section, entries are rendered under these fixed headings,
in this order, and only headings that have entries appear:

- `Breaking changes` (`breaking`)
- `Deprecations` (`deprecation`)
- `New components` (`new_component`)
- `Enhancements` (`enhancement`)
- `Bug fixes` (`bug_fix`)

Each entry renders as `` - `component`: note (#issue) `` with any `subtext`
indented beneath it. Run `make chlog-preview` at any time to see exactly what the
next release section will look like without modifying any files.

Open a pull request against the main `opentelemetry-demo` repo.

### How to Receive Comments

- If the PR is not ready for review, please mark it as
  [`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
- Make sure CLA is signed and all required CI checks are clear.
- Submit small, focused PRs addressing a single
  concern/issue.
- Make sure the PR title reflects the contribution.
- Write a summary that helps understand the change.
- Include usage examples in the summary, where applicable.
- For performance-related changes, include before/after measurements in the
  summary and describe how they were collected.

### How to Get PRs Merged

A PR is considered to be **ready to merge** when:

- It has received approval from
  [Approvers](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#approver)
  /
  [Maintainers](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer).
- Major feedbacks are resolved.
- It has been open for review for at least one working day. This gives people
  reasonable time to review.
- The [documentation][docs] and [Changelog](./CHANGELOG.md) have been updated
  to reflect the new changes.
- Trivial changes (typo, cosmetic, doc, etc.) don't have to wait for one day.

Any Maintainer can merge the PR once it is **ready to merge**. Note, that some
PRs may not be merged immediately if the repo is in the process of a release and
the maintainers decided to defer the PR to the next release train.

If a PR has been stuck (e.g. there are lots of debates and people couldn't agree
on each other), the owner should try to get people aligned by:

- Consolidating the perspectives and putting a summary in the PR. It is
  recommended to add a link into the PR description, which points to a comment
  with a summary in the PR conversation.
- Tagging subdomain experts (by looking at the change history) in the PR asking
  for suggestion.
- Reaching out to more people on the [CNCF OpenTelemetry Community Demo Slack
  channel](https://app.slack.com/client/T08PSQ7BQ/C03B4CWV4DA). If you are new
  to the CNCF Slack community, you can [create an
  account](https://slack.cncf.io/).
- Stepping back to see if it makes sense to narrow down the scope of the PR or
  split it up.
- If none of the above worked and the PR has been stuck for more than 2 weeks,
  the owner should bring it to the OpenTelemetry Community Demo SIG
  [meeting](README.md#contributing).

## Multi-platform Builds

Creating multi-platform builds requires docker buildx to be installed. This
is part of Docker Desktop for macOS, or can be installed using
`apt install docker-buildx` on Ubuntu.

To build and load the multi-platform images locally you will need to configure
docker to use `containerd`. This can be done in Docker Desktop settings on MacOS
or Windows. Please follow
[these instructions](https://docs.docker.com/engine/storage/containerd/#enable-containerd-image-store-on-docker-engine)
to configure Docker Engine on Linux/Ubuntu.

You will need a multi-platform capable builder with a limiter set on parallelism
to avoid errors while building the images. It is recommended to limit the
parallelism to 4. This can be done by specifying a configuration file when
creating the builder. The `buildkitd.toml` file in this repository can be used
as the builder configuration file.

To create a multi-platform builder with a parallelism limit of 4, use the
following command:

```shell
make create-multiplatform-builder
```

A builder will be created and set as the active builder. You can check the
builder status with `docker buildx inspect`. To build multi-platform images for
linux/amd64 and linux/arm64, use the following command:

```shell
make build-multiplatform
```

To build and push multi-platform images to a registry, ensure to set
`IMAGE_NAME` to the name of the registry and image repository to use in the
`.env.override` file and run:

```shell
make build-multiplatform-and-push
```

## Making a new release

Maintainers can create a new release when desired by following these steps.

1. Create a Pull Request that updates the `IMAGE_VERSION` environment variable
   in `.env` to the _new_ version number based on the format `x.x.x` and merge
   it.
2. [Create a new
   release](https://github.com/open-telemetry/opentelemetry-demo/releases/new),
   creating a new tag for the _new_ version number based on main. Automatically
   generate release notes. Prepend a summary of the major changes to the release
   notes.
3. After images for the new release are built and published, create a new Pull
   Request that folds the changelog fragments into `CHANGELOG.md`. Optionally
   run `make chlog-preview` first to review the generated notes, then run
   `make chlog-update VERSION=x.x.x`. This inserts a new `## x.x.x` section
   directly below the `<!-- next version -->` marker (entries grouped by
   `change_type`) and deletes the consumed fragment files, leaving `.chloggen/`
   empty aside from `TEMPLATE.yaml` for the next release. See
   [How fragments become the changelog at release time](#how-fragments-become-the-changelog-at-release-time)
   for the grouping details. Merge the Pull Request.
4. Create a new Pull Request to update the deployment of the demo in the
   [OpenTelemetry Helm
   Charts](https://github.com/open-telemetry/opentelemetry-helm-charts) repo.
   Merge the Pull Request.
5. After the Helm chart is released, create a new Pull Request which updates the
   Demo's Kubernetes manifest by running `make generate-kubernetes-manifests`.
   Merge the Pull Request.

[docs]: https://opentelemetry.io/docs/demo/

By following this guide, you'll have a smoother onboarding experience as a
contributor. Happy coding!