Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
85 lines (55 loc) · 3.6 KB

CONTRIBUTING.md

File metadata and controls

85 lines (55 loc) · 3.6 KB

Contributing to PocketBase

Important

Due to recent LLM spam, PRs are temporary disabled and only existing collaborators can open a PR. If you stumble on a problem that you want to fix, please consider instead opening an issue or discussion with link to your fork (if not obvious - LLM contributions are not welcome). This status may change in the future in case GitHub finally decide to do something about the constant spam, or when I find time to move the project somewhere else.

This document describes how to prepare a PR for a change in the main repository.

Prerequisites

  • Go 1.25+ (for making changes in the Go code)
  • Node 24+ (for making changes in the Superuser UI)

If you haven't already, you can fork the main repository and clone your fork so that you can work locally:

git clone https://github.com/your_username/pocketbase.git

Important

It is recommended to create a new branch from master for each of your bugfixes and features. This is required if you are planning to submit multiple PRs in order to keep the changes separate for review until they eventually get merged.

Making changes in the Go code

PocketBase is distributed as a Go package, which means that in order to run the project you'll have to create a Go main program that imports the package.

The repository already includes such program, located in examples/base, that is also used for the prebuilt executables.

So, let's assume that you already done some changes in the PocketBase Go code and you want now to run them:

  1. Navigate to examples/base
  2. Run go run main.go serve

This will start a web server on http://localhost:8090 with the embedded prebuilt Superuser UI from ui/dist. And that's it!

Before making a PR to the main repository, it is a good idea to:

  • Add unit/integration tests for your changes (we are using the standard testing go package). To run the tests, you could execute (while in the root project directory):

    go test ./...

# or using the Makefile
make test

  • Run the linter - golangci (see how to install):

    golangci-lint run -c ./golangci.yml ./...

# or using the Makefile
make lint

Making changes in the Superuser UI

PocketBase Superuser UI is a single-page application (SPA) built with Svelte and Vite.

To start the Superuser UI:

  1. Navigate to the ui project directory
  2. Run npm install to install the node dependencies
  3. Start vite's dev server 
    npm run dev

You could open the browser and access the running Superuser UI at http://localhost:5173.

Since the Superuser UI is just a client-side application, you need to have the PocketBase backend server also running in the background (either manually running the examples/base/main.go or download a prebuilt executable).

Note

By default, the Superuser UI is expecting the backend server to be started at http://localhost:8090, but you could change that by creating a new ui/.env.development.local file with PB_BACKEND_URL = YOUR_ADDRESS variable inside it.

Every change you make in the Superuser UI should be automatically reflected in the browser at http://localhost:5173 without reloading the page.

Once you are done with your changes, you have to build the Superuser UI with npm run build, so that it can be embedded in the go package. And that's it - you can make your PR to the main PocketBase repository.