Nikolay Tatarinov
a3a4c0e896
- Updated CONTRIBUTING.md to clarify the use of Makefile targets for running tasks inside Docker, eliminating the need for local Go or Node installations. - Introduced docker-compose.tools.yml for backend and frontend tools, allowing for streamlined testing, linting, and formatting. - Created Dockerfile.tools to set up a Go environment with necessary tools for testing and linting. - Modified Makefile to include separate targets for backend and frontend tests, improving clarity and usability. - Updated documentation in development.md and testing.md to reflect the new Docker-based workflow for running tests and development tasks.
48 lines
2.4 KiB
Markdown
48 lines
2.4 KiB
Markdown
# Contributing to hnh-map
|
|
|
|
## Getting started
|
|
|
|
Clone the repository and run the project locally (see [Development](docs/development.md)):
|
|
|
|
- **Option A:** Docker Compose for development: `docker compose -f docker-compose.dev.yml up` (or `make dev`). Frontend on 3000, backend on 3080.
|
|
- **Option B:** Run Go backend from the repo root (`go run ./cmd/hnh-map -grids=./grids -port=8080`) and Nuxt separately (`cd frontend-nuxt && npm run dev`). Ensure the frontend can reach the backend (proxy or same host).
|
|
|
|
## Code layout
|
|
|
|
The backend follows a layered architecture: **Store → Services → Handlers**.
|
|
|
|
- **Backend:** Entry point is `cmd/hnh-map/main.go`. Application logic lives in `internal/app/`:
|
|
- `app.go` — `App` struct, domain types, SPA serving, constants.
|
|
- `router.go` — route registration.
|
|
- `topic.go` — pub/sub for real-time updates.
|
|
- `migrations.go` — database migrations.
|
|
- `store/` — bbolt database access layer (`db.go`, `buckets.go`).
|
|
- `services/` — business logic (`auth.go`, `map.go`, `admin.go`, `client.go`, `export.go`).
|
|
- `handlers/` — HTTP handlers (`api.go`, `auth.go`, `map.go`, `client.go`, `admin.go`, `tile.go`, `handlers.go`, `response.go`).
|
|
- `apperr/` — domain error types.
|
|
- `response/` — shared JSON response helpers.
|
|
- **Frontend:** Nuxt 3 app in `frontend-nuxt/` (pages, components, composables, layouts, plugins, `public/gfx`). It is served by the Go backend at root `/` with baseURL `/`.
|
|
|
|
## Formatting, linting, and tests
|
|
|
|
Use Makefile targets; they run inside Docker via `docker-compose.tools.yml`, so you do not need Go or Node installed for these tasks:
|
|
|
|
```bash
|
|
make fmt # Format all code (Go + frontend)
|
|
make lint # Run Go linter (golangci-lint) and frontend ESLint
|
|
make test # Run backend and frontend tests
|
|
```
|
|
|
|
Or run manually on the host if you have Go and Node:
|
|
|
|
- Go: `go fmt ./...` and `golangci-lint run`
|
|
- Frontend: `npm --prefix frontend-nuxt run lint` and `npm --prefix frontend-nuxt run format`
|
|
- Tests: `go test ./...` and `npm --prefix frontend-nuxt run test`
|
|
|
|
Always format and lint before committing. Add or update tests if you change behaviour.
|
|
|
|
## Submitting changes
|
|
|
|
- Open a pull request with a clear description of the change.
|
|
- Mention compatibility with [hnh-auto-mapper-server](https://github.com/APXEOLOG/hnh-auto-mapper-server) if relevant (e.g. client protocol or API).
|