Skip to content

Latest commit

 

History

History
156 lines (105 loc) · 4.45 KB

CONTRIBUTING.md

File metadata and controls

156 lines (105 loc) · 4.45 KB
Raw

Gitbase Web Contribution Guidelines

As all source{d} projects, this project follows the source{d} Contributing Guidelines.

In addition to those guidelines, this document describes how to build and run the application for development purposes.

Requirements

Refer to the main README for the common requirements and configuration environment variables.

Make sure you also satisfy these requirements:

Run bblfsh and gitbase Dependencies

As with a normal deployment, if you don't use Docker Compose you will need to configure a gitbase server, and a bblfsh server. It is recommended to read their documentation, but here is a quick guide on how to run both as docker containers.

Launch bblfshd. The -drivers image already contains all the recommended drivers:

$ docker run \
    --privileged \
    --publish 9432:9432 \
    --name bblfsh \
    bblfsh/bblfshd:latest-drivers

gitbase will serve Git repositories, so you will need to to populate a directory with them:

$ mkdir $HOME/repos
$ cd $HOME/repos
$ git clone git@github.com:src-d/gitbase.git
$ git clone git@github.com:bblfsh/bblfshd.git
$ git clone git@github.com:src-d/gitbase-web.git

Launch gitbase:

$ docker run \
    --publish 3306:3306 \
    --link bblfsh \
    --volume $HOME/repos:/opt/repos \
    --env BBLFSH_ENDPOINT=bblfsh:9432 \
    --name gitbase \
    srcd/gitbase

Architecture

The application is a Go binary that serves the static files and the API used for the UI.

The static files (html, js, and css) are generated by yarn, embedded in the Go binary using go-bindata, and served from the binary itself.

API

The backend API is documented in the Rest API guide

Development

Each one of the following sections describes an alternative method to run the project from sources. You may use the one that suits your needs.

They all require that the project is cloned into your $GOPATH.

$ go get -d -u github.com/src-d/gitbase-web/...
$ cd $GOPATH/github.com/src-d/gitbase-web

Run from Sources

The following command will build the frontend and serve it from the Go backend:

$ make serve

This will start a server locally, which you can access at http://localhost:8080.

Run Using webpack Hot Module Replacement

Instead of rebuilding the frontend and restarting the backend every time you make a change, you may instead run the backend to provide the API, and use webpack to serve the frontend.

In one terminal run the Go backend:

$ LOG_LEVEL=DEBUG go run cmd/gitbase-web/main.go serve

In another terminal, run the frontend:

$ yarn --cwd frontend install
$ yarn --cwd frontend start

Run with Docker Compose from Sources

The file docker-compose.build.yml overrides the default compose file. Using it a new docker image, gitbase-web-dev, will be created from the current sources.

$ make dependencies
$ make packages
$ GITBASEPG_REPOS_FOLDER=$HOME/repos docker-compose \
    -f docker-compose.yml -f docker-compose.build.yml \
    up --force-recreate --build

For convenience you may run the same commands with:

$ make compose-serve

Build a Docker Container

These commands will build a stand-alone docker image, that will require external gitbase and bblfshd servers.

$ make dependencies
$ make packages
$ make docker-build

Testing

Lint

Use make lint to make sure the code follows the project's coding style.

$ make lint

Unit Tests

The command make test will run JavaScript and Go tests.

$ make test

Integration Tests

Use the GITBASEPG_INTEGRATION_TESTS=true environment variable with the same make test command.

The integration tests require that gitbase and bblfshd are running and reachable. See the Requirements section above for more details.

It is also required to configure the running gitbase to serve a copy of the https://github.com/src-d/gitbase-web repository.

$ GITBASEPG_INTEGRATION_TESTS=true make test