Missing info in Contributor Guide

[RichardChukwu]

This is part of open-telemetry/sig-contributor-experience#31

The goal is to clarify Run/build prerequisites, testing and address common build issues to make it easier for first-time contributors to get started with opentelemetry-erlang.

I'd like to verify these info before adding to the proposed PR for fixing:

Local Run/Build

Setting Up and Running the Project Locally

To run the project locally, follow these steps:

Start required services:

docker compose up -d

Set up Erlang/OTP and Rebar3 and Verify setup (Ensure you have the correct versions as specified in the prerequisites):

Run the compilation step to check for errors:

rebar3 compile

Testing

To execute tests, use the following commands:

Unit Tests (EUnit):

rebar3 eunit

Integration and Functional Tests (Common Test):

rebar3 ct

Test results and logs can be viewed in a browser by opening:

build/test/logs/index.html

Elixir Tests

Elixir tests are run in two places:

1. Inside apps/opentelemetry_api/:

mix test

2. At the top level:

mix test --no-start test/otel_tests.exs test/otel_metric_tests.exs

Troubleshooting Guide

Debugging Common Failures

• Test Failures: Check the test logs in _build/test/logs/.

• Compilation Issues: Ensure correct OTP and Rebar3 versions are installed.

• Dialyzer Warnings: Ensure rebar3 compile completes successfully.

Developer Setup and Language Servers

For improved development experience, consider using the following Language Server Protocols (LSPs):

• Erlang LSP: Erlang Language Platform

• Installing it removes the need for an additional type-checking step:

elp eqwalize-all

• Install from: Erlang Language Platform Releases

• Elixir LSP: Elixir LS

Feedback are welcome to ensure all info here are correct

Ongoing PR: #825

CC: @tsloughter

[tsloughter]

You can remove the --cover part of each command.

No need to include a note about reviewing rebar.lock.

If we are just talking about local testing you can remove the part about mikepenz/action-junit-report@v5

I'd add a note that rebar3 ct results and logs can be viewed in a browser by going to _build/test/logs/index.html.

You may want to mention the Erlang LSP I prefer https://whatsapp.github.io/erlang-language-platform/ for developer setup.

Using the LSP also removes the need for an additional step which you'll find in the github actions under eqWAlizer that needs to be run to type check the project:

$ elp eqwalize-all

After installing https://github.com/WhatsApp/erlang-language-platform/releases/

Lastly, Elixir tests (in github actions these are found in elixir.yml) are run in two places, first in apps/opentelemetry_api/:

$ mix test

And also at the top level:

$ mix test --no-start test/otel_tests.exs test/otel_metric_tests.exs

And can mention the Elixir LSP https://github.com/elixir-lsp/elixir-ls

[RichardChukwu]

All changes effected @tsloughter kindly check