> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Contributing

walkerOS is open source and will remain open source. We believe companies should own their data infrastructure. True data ownership only comes when you control your data collection. No vendor lock-in, no surprises. You own your code, your data, your future.

There are multiple ways to contribute, and we appreciate them all.

## Getting started[​](#getting-started "Direct link to Getting started")

### Devcontainer (recommended)[​](#devcontainer-recommended "Direct link to Devcontainer (recommended)")

The easiest way to start developing is using the [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) setup. It automatically installs all dependencies, extensions, and AI-assisted development tooling.

1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension in VS Code
2. Open the command palette and select `Dev Containers: Reopen in Container`
3. Wait for the container to build. You're ready to code

The `skills/` folder contains step-by-step guides that work with any AI assistant.

### Manual setup[​](#manual-setup "Direct link to Manual setup")

If you prefer a local setup:

```
npm install                    # Install dependencies
npm run build                  # Build all packages
npm run dev                    # Start watch mode

# Verification scripts (use the smallest scope that proves your change)
npm run verify:touched -- core # One package: typecheck + lint + test
npm run verify:affected        # All packages affected since origin/main
npm run test:smoke             # Critical path + affected (PR-ready check)
npm run test                   # Full suite (release / on demand)
npm run lint                   # Full lint
npm run typecheck              # Full typecheck
```

The verification scripts compose with turbo cache and the `[origin/main]` filter. For day-to-day work, prefer `verify:touched` for the package you edited and `verify:affected` before opening a PR. Save the full root-level runs for release prep.

## Ways to contribute[​](#ways-to-contribute "Direct link to Ways to contribute")

### Code[​](#code "Direct link to Code")

* Fix bugs or implement new features
* Create new destinations or sources (see `skills/create-destination` and `skills/create-source` for guidance)
* Improve existing packages

### Documentation[​](#documentation "Direct link to Documentation")

The documentation lives in `website/docs/`. To run the docs locally:

```
cd website && npm run start
```

* Improve existing documentation
* Add examples and use cases
* Fix typos and clarify explanations

### Community[​](#community "Direct link to Community")

* [Report bugs](https://github.com/elbwalker/walkerOS/issues)
  <!-- -->
  (issue templates available)
* Suggest features
* Answer questions from other users

## Development workflow[​](#development-workflow "Direct link to Development workflow")

walkerOS uses a test-driven development approach with [Jest](https://jestjs.io/). Please run tests before submitting pull requests.

### Adding a changeset[​](#adding-a-changeset "Direct link to Adding a changeset")

When your PR includes changes that should be released, add a changeset:

```
npx changeset
```

1. Select the packages your PR affects

2. Choose the version bump type:

   <!-- -->

   * **patch:** bug fixes, minor improvements
   * **minor:** new features (backwards compatible)
   * **major:** breaking changes

3. Write a brief summary of the changes

4. Commit the generated `.changeset/*.md` file with your PR

Changesets help generate accurate changelogs and version packages correctly. Not every PR needs a changeset. Skip it for documentation, CI changes, or internal refactoring that doesn't affect published packages.

### Package structure[​](#package-structure "Direct link to Package structure")

The project is organized as a monorepo:

```
packages/

├── core/           # Types, utilities, schemas

├── collector/      # Event processing engine

├── config/         # Shared tooling config

├── web/            # Browser: sources/, destinations/

└── server/         # Node.js: sources/, destinations/



apps/

├── quickstart/     # Validated examples

├── walkerjs/       # Browser bundle

└── demos/          # Demo applications
```

## Resources[​](#resources "Direct link to Resources")

**For deeper guidance:**

* `skills/`: step-by-step guides for common tasks (creating destinations, sources, testing strategies)
* `AGENT.md`: quick reference for contributors and AI assistants

**Get in touch:**

* [Open an issue](https://github.com/elbwalker/walkerOS/issues)
* [Send an email](mailto:hello@elbwalker.com)
* [Schedule a call](https://calendly.com/elb-alexander/30min)
* [Connect on LinkedIn](https://www.linkedin.com/in/alexanderkirtzel/)