Skip to content

Latest commit

 

History

History
154 lines (103 loc) · 5.18 KB

CONTRIBUTING.md

File metadata and controls

154 lines (103 loc) · 5.18 KB
Raw

Contributing to ZincSearch

Setting up development environment

Prerequisite

ZincSearch uses Go (For server) and VueJS (For Web UI)

You must have following installed:

  1. Git
  2. Go 1.16 + (We recommend go 1.19+)
  3. nodejs v14+ and npm v6+

Building from source code

Lets clone the repo and get started

git clone https://github.com/zincsearch/zincsearch
cd zincsearch

Now let's build the UI

cd web
npm install
npm run build
cd ..

Output will be stored in web/dist folder. web/dist will be embedded in ZincSearch binary when ZincSearch go application is built.

It is important that you build the web app every time you make any changes to javascript code as the built code is then embedded in go application.

Time to build the go application now

Download the dependencies

go mod tidy # this will download the go libraries used by zincsearch

Simple:

go build -o zincsearch cmd/zincsearch/main.go # will build the ZincSearch binary

Advanced

CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w -X github.com/zincsearch/zincsearch/pkg/meta.Version=${VERSION} -X github.com/zincsearch/zincsearch/pkg/meta.CommitHash=${COMMIT_HASH} -X github.com/zincsearch/zincsearch/pkg/meta.BuildDate=${BUILD_DATE}" -o zincsearch cmd/zincsearch/main.go

Setting GOOS and GOARCH appropriately allows for cross platform compilation. Check Official docs for all possible values and combinations. This gist is also great.

Setting CGO_ENABLED=0 allows for static linking, which results in a single binary output that has no dependencies.

setting up ldflags allows for passing values like version number to the binary at build time instead of hardcoding the value in source code. Generally the version number is set by the CI pipeline during build by using the git tag.

Developing

Once you have the source code cloned you can start development.

There are 2 areas of development.

  1. UI
  2. Server

Server

go mod tidy
ZINC_FIRST_ADMIN_USER=admin ZINC_FIRST_ADMIN_PASSWORD=Complexpass#123 go run cmd/zincsearch/main.go

This will start the ZincSearch API server on port 4080

environment variables ZINC_FIRST_ADMIN_USER and ZINC_FIRST_ADMIN_PASSWORD are required only first time when ZincSearch is started.

UI

cd web
npm install
npm run dev

This will start UI server on port 8080

In order for you to effectively use the UI you would want to have the ZincSearch API server running in a separate window that will accept requests from the UI.

Swagger

The server also exposes a Swagger API endpoint which you can see by visiting the /swagger/index.html path. It uses gin-swagger to mark API endpoints with comment annotations and swag to generate the API spec from the annotations to Swagger Documentation 2.0.

If you update the annotations, you need to also regenerate the Swagger documentation by running the swagger.sh script located at the base project folder:

./swagger.sh
2022/05/31 10:18:13 Generate swagger docs....
2022/05/31 10:18:13 Generate general API Info, search dir:./
2022/05/31 10:18:13 Generating auth.LoginRequest
2022/05/31 10:18:13 Generating auth.LoginSuccess
2022/05/31 10:18:13 Generating auth.SimpleUser
2022/05/31 10:18:13 Generating auth.LoginError
2022/05/31 10:18:13 create docs.go at  docs/docs.go
2022/05/31 10:18:13 create swagger.json at  docs/swagger.json
2022/05/31 10:18:13 create swagger.yaml at  docs/swagger.yaml
```

## Build docker image

Make sure that you have [docker](https://docs.docker.com/get-docker/).

Simple build:

```shell
docker build --tag zincsearch:latest . -f Dockerfile

Multi-arch build

In order to build multi-arch builds you will need buildx installed. You will need to pass the platform flag for the platform that you want to build.

docker buildx build --platform linux/amd64 --tag zinc:latest-linux-amd64 . -f Dockerfile.hub

Checks in CI pipeline

We check for following in CI pipeline for any pull requests.

  1. Unit test code coverage for go code.
    • If code coverage is less than 81% (according to go test) the CI tests will fail.
    • You can test coverage yourself by running ./coverage.sh
    • We use codecov for visualizing code coverage of go code, codecov updates coverage for every PR through a comment. It allows you to see missing coverage for any lines.
  2. Linting in Javascript for GUI
    • We run eslint for javascript anf any linting failures will result in build failures.
    • You can test for linting failures by running ./lint.sh in web folder.
    • You can also fix automatically fixable linting error by running npm run lint-autofix

How to contribute code

  1. Fork the repository on github (e.g. awesomedev/zincsearch)
  2. Clone the repo from the forked repository ( e.g. awesomedev/zincsearch) to your machine.
  3. create a new branch locally.
  4. Make the changes to code.
  5. Push the code to your repo.
  6. Create a PR
  7. Make sure that the automatic CI checks pass for your PR.