diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c20144c4..54c7cf90 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,4 @@ -Contributing to PocketBase -====================================================================== +# Contributing to PocketBase Thanks for taking the time to improve PocketBase! @@ -9,26 +8,26 @@ This document describes how to prepare a PR for a change in the main repository. - [Making changes in the Go code](#making-changes-in-the-go-code) - [Making changes in the Admin UI](#making-changes-in-the-admin-ui) - ## Prerequisites -- Go 1.18+ (for making changes in the Go code) +- Go 1.19+ (for making changes in the Go code) - Node 16+ (for making changes in the Admin 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. +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: @@ -41,20 +40,22 @@ This will start a web server on `http://localhost:8090` with the embedded prebui - 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): - ```sh - go test ./... - # or using the Makefile - make test - ``` + ```sh + go test ./... + + # or using the Makefile + make test + ``` - Run the linter - **golangci** ([see how to install](https://golangci-lint.run/usage/install/#local-installation)): - ```sh - golangci-lint run -c ./golangci.yml ./... - # or using the Makefile - make lint - ``` + ```sh + golangci-lint run -c ./golangci.yml ./... + + # or using the Makefile + make lint + ``` ## Making changes in the Admin UI @@ -65,14 +66,15 @@ To start the Admin UI: 1. Navigate to the `ui` project directory 2. Run `npm install` to install the node dependencies 3. Start vite's dev server - ```sh - npm run dev - ``` + ```sh + npm run dev + ``` You could open the browser and access the running Admin UI at `http://localhost:3000`. Since the Admin 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 Admin 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 Admin UI should be automatically reflected in the browser at `http://localhost:3000` without reloading the page. diff --git a/README.md b/README.md index 2f70c260..a8fd8d1f 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,10 @@ **For documentation and examples, please visit https://pocketbase.io/docs.** -> ⚠️ Please keep in mind that PocketBase is still under active development +> [!WARNING] +> Please keep in mind that PocketBase is still under active development > and therefore full backward compatibility is not guaranteed before reaching v1.0.0. - ## API SDK clients The easiest way to interact with the API is to use one of the official SDK clients: @@ -30,7 +30,6 @@ The easiest way to interact with the API is to use one of the official SDK clien - **JavaScript - [pocketbase/js-sdk](https://github.com/pocketbase/js-sdk)** (_browser and node_) - **Dart - [pocketbase/dart-sdk](https://github.com/pocketbase/dart-sdk)** (_web, mobile, desktop_) - ## Overview PocketBase could be [downloaded directly as a standalone app](https://github.com/pocketbase/pocketbase/releases) or it could be used as a Go framework/toolkit which allows you to build @@ -98,10 +97,11 @@ To build the minimal standalone executable, like the prebuilt ones in the releas 1. Clone/download the repo 2. Navigate to `examples/base` 3. Run `GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build` - (_https://go.dev/doc/install/source#environment_) + (_https://go.dev/doc/install/source#environment_) 4. Start the created executable by running `./base serve`. The supported build targets by the non-cgo driver at the moment are: + ``` darwin amd64 darwin arm64 @@ -121,6 +121,7 @@ windows arm64 PocketBase comes with mixed bag of unit and integration tests. To run them, use the default `go test` command: + ```sh go test ./... ``` @@ -133,7 +134,6 @@ If you discover a security vulnerability within PocketBase, please send an e-mai All reports will be promptly addressed, and you'll be credited accordingly. - ## Contributing PocketBase is free and open source project licensed under the [MIT License](LICENSE.md). @@ -153,5 +153,6 @@ PocketBase has a [roadmap](https://github.com/orgs/pocketbase/projects/2) and I Don't get upset if I close your PR, even if it is well executed and tested. This doesn't mean that it will never be merged. Later we can always refer to it and/or take pieces of your implementation when the time comes to work on the issue (don't worry you'll be credited in the release notes). -_Please also note that PocketBase was initially created to serve as a new backend for my other open source project - [Presentator](https://presentator.io) (see [#183](https://github.com/presentator/presentator/issues/183)), -so all feature requests will be first aligned with what we need for Presentator v3._ +> [!NOTE] +> PocketBase was initially created to serve as a new backend for my other open source project - [Presentator](https://presentator.io) (see [#183](https://github.com/presentator/presentator/issues/183)), +> so all feature requests will be first aligned with what we need for Presentator v3.