Contributing

Contribution guide

Thank you for your interest in contributing to our projects! Read our Code of Conduct (opens in a new tab) to keep our community approachable and respectable.

This document contains a few notes to get you started with your contribution.

Identify the correct repository

We develop our packages in multiple repositories. If you already know which package you want to work on, simply follow the repository link of its package.json, which is also displayed on npmjs.com (opens in a new tab). For example, the @open-pioneer/map (opens in a new tab) package links back to its repository trails-openlayers-base-packages (opens in a new tab).

Our current set of repositories is:

Starter repo (opens in a new tab): Serves as a baseline for new trails projects. This repository also hosts the Documentation (opens in a new tab).
Core packages (opens in a new tab): Contains the runtime package and other central packages.
OpenLayers base packages (opens in a new tab): Contains packages using OpenLayers to render a map.
Community packages (opens in a new tab): Contains specialized packages maintained by the community.
Build tools (opens in a new tab): Contains our build tooling such as the Vite plugin.

Report an issue

If you found a bug, please open an issue in an appropriate repository and provide us with clear instructions to reproduce it. Please attach a reproducible sample that demonstrates the problem. Good examples are:

a failing test case
a small code snippet
a sample repository (e.g. a fork of the starter repository)

Our repositories are configured with issue templates that can help you write a good bug report.

Making a small change

Very small changes (such as updates to the documentation) can be done without setting up the project for local development. Simply create a fork of the repository via GitHub’s UI and apply your changes by editing the files in question in the browser. Then, follow the instructions in Creating a pull request to contribute your changes.

Legal requirements

Contributing to the Open Pioneer project requires signing a Contributor License Agreement (CLA) before source code can be merged. This can be done by your employer or by yourself.

To obtain a copy of the CLA, please email to contact@open-pioneer.dev (We do not have an automated process in place at this time).

Set up the project

To start with local development, take a look at getting started. Most repositories in our organization have a uniform layout, so the guide applies to them as well. For local differences, take a look at a repository’s README.

To get you productive quickly, here are the most important commands (note: there may be local differences per repository).

Installing dependencies

1
$ pnpm install

Running the local development mode

For repositories that use Vite (opens in a new tab), the following command will start the development mode. It will start a local server and print its address, which you can then open in your browser. The browser will keep reloading while you edit source code files, immediately rendering your changes.

1
$ pnpm dev
2

3
> starter@ dev /home/michael/projects/pioneer/starter
4
> vite
5

6

7
  VITE v4.5.3  ready in 606 ms
8

9
  ➜  Local:   http://localhost:5173/
10
  ➜  Network: use --host to expose
11
  ➜  press h to show help

Git and IDE setup

All text files must use UTF-8 encoding. This is usually the default.
All text files must use Unix line endings (\n). On windows, either configure your IDE to use Unix line endings or use git’s autocrlf (opens in a new tab) feature:
Terminal window
```
1
$ git config --global core.autocrlf input
```
We keep a linear history in our public branches. You can make rebase the default (instead of merge) to avoid accidental merge commits. Note: this can also be done on a per-repository basis.
Terminal window
```
1
$ git config --global pull.rebase true
```
Paths to JavaScript modules can get rather long on windows in combination with PNPM. If you see weird errors (I/O errors, file not found, etc.) when you’re trying to install dependencies or run the development server, try moving the git repository to a shorter path on disk (less nesting, shorter name).
Either use eslint’s autofix feature or your IDE to ensure that your files contain license headers.

The following snippet can be used in VSCode. Create a snippet via “Ctrl+Shift+P –> Configure User Snippets” (either globally or in this project). The following example snippet appears in autocomplete when you start typing “license” in a JavaScript/TypeScript file:
```
1
{
2
    "License header": {
3
        "scope": "javascript,typescript",
4
        "prefix": "license",
5
        "body": [
6
            "// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)",
7
            "// SPDX-License-Identifier: Apache-2.0"
8
        ]
9
    }
10
}
```

Creating a pull request

We are always happy to receive pull requests from the community. Small fixes or improvements to the documentation will usually be accepted right away. If you plan to make a larger contribution (new packages, new features, refactoring, etc.) consider reaching out to the maintainers first. This can be done, for example, by commenting on an existing issue or by creating a new one. The contributions board (opens in a new tab) contains a list of new, desired features for Open Pioneer - Trails. Contributions are very welcome here!

This way, you can avoid unnecessary work and ensure that your contribution is in line with the project’s goals. This will also reduce the risk of your PR being rejected. If you want to share your own ideas and more specialized functionalities with the community, you can also consider creating a pull request in the community repository.

To create a pull request:

First, fork the repository via GitHub’s UI and clone your fork (if you have write permissions to the repository, you can skip this step).
Then, create a branch with a sensible name. We use simple branch prefixes to keep some order:
- feature/SCOPE
- fix/SCOPE
- chore/SCOPE
- docs/SCOPE
where SCOPE is up to you, but it should be a short and descriptive identifier.
Make your changes in one or more commits. We do not have a strict commit message convention. Most pull requests are merged by squashing all changes, so you can make as many commits as you like.

When fixing bugs or implementing new features, make sure to include appropriate tests alongside your implementation.

In general, make sure that automated tests (Typescript checks, unit tests, …) are successful, otherwise your changes will not be merged. Tests are executed automatically when creating a commit and also when creating a pull request. For more details, see Running tests.
Run pnpm changeset to create a description of your changes. This will create a file that will be used to generate a changelog entry and a future release. Your changeset file should list all packages that are affected by your change. Don’t forget to include this file in your pull request. Do not update versions of workspace packages manually.

Go here to learn more about Changesets (opens in a new tab).

Some changes (e.g. in configuration files) don’t need a real changeset file. You can generate an empty one by running pnpm changeset add --empty instead.
Push your changes into your fork (or branch) and create a pull request via GitHubs UI. Please give your pull request a good title and a good description. If your pull request addresses an issue, you should link to it from your PR’s description.

Running tests

Checking for TypeScript errors

We use TypeScript (opens in a new tab) to provide good interfaces and detect potential problems. We recommend running TypeScript alongside your code, so you are immediately aware of any issues.

1
# This command keeps running and shows errors (or not) after you save a file.
2
$ pnpm watch-types
3

4
# This command does a one-off check and exits.
5
$ pnpm check-types

Unit tests

We use Vitest (opens in a new tab) to write our tests. Files that are named *.test.ts[x] (or js[x]) are automatically discovered and executed:

1
~/projects/pioneer/core-packages$ pnpm test
2

3
> core-packages@0.0.1 test /home/michael/projects/pioneer/core-packages
4
> vitest
5

6

7
 DEV  v0.34.6 /home/michael/projects/pioneer/core-packages/src
8

9
 ✓ packages/local-storage/LocalStorageServiceImpl.test.ts (22)
10

11
 ... SNIP ...
12

13
 Test Files  22 passed (22)
14
      Tests  152 passed (152)
15
   Start at  16:11:36
16
   Duration  6.92s (transform 2.01s, setup 5.48s, collect 19.48s, tests 5.62s, environment 9.17s, prepare 3.87s)
17

18

19
 PASS  Waiting for file changes...
20
       press h to show help, press q to quit

Vitest will keep running and will re-execute affected test cases when you change a source file.

You can also run tests of certain directories (or files) only:

1
# Executes only the tests found in the given directory (or file)
2
$ pnpm test src/packages/SOME_PACKAGE
3
$ pnpm test src/packages/SOME_PACKAGE/some-file.test.ts

For more information, see Vitest’s CLI options (opens in a new tab).