mirror of
https://github.com/karust/openserp.git
synced 2026-08-05 16:53:54 +08:00
134 lines
3.6 KiB
Markdown
134 lines
3.6 KiB
Markdown
# Contributing to OpenSERP
|
|
|
|
## Fastest Path to a Merged PR
|
|
|
|
1. Pick a focused issue, ideally one labeled `good first issue`.
|
|
2. Comment on the issue with the approach you plan to take.
|
|
3. Keep the PR narrow: one bug, one parser fallback, one docs page, or one engine step.
|
|
4. Run `make fmt`, `make lint`, and `make test` before opening the PR.
|
|
5. Explain what changed, why it changed, and how you tested it.
|
|
|
|
Good first issues are curated in [`GOOD_FIRST_ISSUES.md`](https://github.com/karust/openserp/blob/main/docs/GOOD_FIRST_ISSUES.md).
|
|
New engine work should start with [`ADDING_AN_ENGINE.md`](https://github.com/karust/openserp/blob/main/docs/ADDING_AN_ENGINE.md).
|
|
|
|
## Development Setup
|
|
|
|
### Prerequisites
|
|
|
|
- Go 1.24+
|
|
- Chromium/Chrome (only required for browser-mode work and integration tests)
|
|
- Optional: Docker
|
|
- Optional: `make` and `golangci-lint` for the same local workflow used by CI
|
|
|
|
### Clone, build, run
|
|
|
|
```bash
|
|
git clone https://github.com/karust/openserp.git
|
|
cd openserp
|
|
make build
|
|
make run
|
|
```
|
|
|
|
### Test commands
|
|
|
|
Unit tests (default, no browser/network assumptions):
|
|
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
Integration tests (explicitly enabled):
|
|
|
|
```bash
|
|
make test-integration
|
|
```
|
|
|
|
Notes:
|
|
|
|
- Integration tests are gated by `testutil.RequireIntegration(t)`.
|
|
- Do not create browser instances in `init()` or package-level variables.
|
|
|
|
## Adding a New Search Engine
|
|
|
|
### 1) Create engine package
|
|
|
|
Create a new folder (example: `myengine/`) with:
|
|
|
|
- `myengine/url.go` (`BuildURL`, and `BuildImageURL` when image support exists)
|
|
- `myengine/search.go` (browser mode implementation)
|
|
- `myengine/search_raw.go` (optional raw mode implementation)
|
|
|
|
### 2) Implement `core.SearchEngine`
|
|
|
|
Your engine type must implement:
|
|
|
|
- `Search(context.Context, core.Query) ([]core.SearchResult, error)`
|
|
- `SearchImage(context.Context, core.Query) ([]core.SearchResult, error)`
|
|
- `IsInitialized() bool`
|
|
- `Name() string`
|
|
- `GetRateLimiter() *rate.Limiter`
|
|
|
|
Use the existing engines (for example `google/`) as the reference pattern.
|
|
|
|
### 3) Register the engine in server wiring
|
|
|
|
Update [`cmd/serve.go`](../cmd/serve.go):
|
|
|
|
- Add engine spec in `browserEngineSpecs()`
|
|
- Add raw-mode handling if raw support exists
|
|
|
|
### 4) Add config block
|
|
|
|
Update [`config.yaml`](../config.yaml) with your engine section:
|
|
|
|
- `rate_requests`
|
|
- `rate_burst`
|
|
- optional `proxy` tag
|
|
- optional engine-specific fields
|
|
|
|
### 5) Add tests
|
|
|
|
- URL builder tests (table-driven)
|
|
- Parser tests (prefer deterministic fixtures in `testdata/`)
|
|
- Integration tests guarded by `testutil.RequireIntegration(t)`
|
|
|
|
See [`ADDING_AN_ENGINE.md`](https://github.com/karust/openserp/blob/main/docs/ADDING_AN_ENGINE.md) for the full checklist.
|
|
|
|
## Code Style and Quality Checks
|
|
|
|
Run these before opening a PR:
|
|
|
|
```bash
|
|
make fmt
|
|
make lint
|
|
make test
|
|
```
|
|
|
|
Guidelines:
|
|
|
|
- Return `error` values instead of panicking in library code.
|
|
- Reuse existing patterns in `core/` and existing engines.
|
|
- Add comments only for non-obvious decisions (why, not what).
|
|
|
|
## Test Categories
|
|
|
|
- Unit tests: deterministic tests that run with `go test ./...` and do not require browser/network.
|
|
- Integration tests: live/browser/network dependent tests gated by `OPENSERP_INTEGRATION_TESTS=1`.
|
|
|
|
When adding tests, keep unit and integration behavior clearly separated.
|
|
|
|
## Pull Request Process
|
|
|
|
For each PR:
|
|
|
|
1. Describe what changed and why.
|
|
2. Link the related issue (if available).
|
|
3. Include or update tests for behavior changes.
|
|
4. Include updated docs when API/config/contracts change.
|
|
|
|
If you change API behavior, update:
|
|
|
|
- [`openapi.yaml`](openapi.yaml)
|
|
- [`../README.md`](../README.md)
|
|
- [`ARCHITECTURE.md`](ARCHITECTURE.md) when flow/design changes
|