Skip to content

Developer Guide

Jump to bottom
Yosuke Mizutani edited this page Jan 8, 2021 · 22 revisions

This document is for all developers / contributors of Shogi Playground.

1. Getting Started

Here we introduce how to set up your local environment.

1.1 Install Prerequisites

Some build commands are written in Makefile. You will need the make command to help automate the development process. Development commands are designed to be run on Mac OS.

The following development tools require Java 8 or later. From Oracle's website, install the latest version of Java Development Kit (JDK) on your platform.

Make sure to have JDK 8+ installed (output may vary).

$ java -version
java version "1.8.0_201"
Java(TM) SE Runtime Environment (build 1.8.0_201-b09)
Java HotSpot(TM) 64-Bit Server VM (build 25.201-b09, mixed mode)

Note: Please avoid using older versions than Java 8 u101. They will cause https certificate issues when sbt attempts to download dependencies.

Important: Avoid JDK 13 and later as noted on sbt's website. A workaround should be to install jenv and configure JDK 8 in your system.

Shogi Playground is developed with Scala and the build tool sbt. Install the latest version of sbt from the link above.

Make sure to have sbt installed (output may vary). The version must be 1.0.0 or later.

$ sbt sbtVersion
[warn] No sbt.version set in project/build.properties, base directory: /proj/mogproject
[info] Set current project to mogproject (in build file:/proj/mogproject/)
[info] 1.2.8

Node.js and npm are required for unit-testing. Install the latest version of Node.js from the official website.

Make sure to have npm installed (output may vary).

$ npm -v
6.4.1

We use Python 3 to launch a local web server for testing. Make sure that python3 command is available on your platform.

$ python3 --version
Python 3.7.2

1.2 Clone Repositories

Shogi Playground depends on the follwoing repositories.

mog-core-scala is a library for core shogi rules as well as input / output definitions. The mate solver is also included in this library. The library should work with both Scala and Scala.js.

Used for: Shogi Playground, Shogi Playground Live!, Shogi Bot, Shogi Playground APIs, mog-image

mog-frontend is a front-end library for Shogi Playground and Shogi Playground Live! Using the git command, please clone this repository.

Example: git clone git@github.com:mogproject/mog-frontend.git

Used for: Shogi Playground, Shogi Playground Live!

  • mog-playground (this repository)

In most cases, you will not need to update the code in mog-playground.

1.3 Build mog-frontend

Once you have cloned the mog-frontend library, you can build source code locally. The following commands should be run in your mog-frontend root directory.

  • Install Node.js libraries

If you do not have the following libraries globally, install them using the npm command.

npm install jsdom -g
npm install uglify-js -g
npm install uglifycss -g
  • Build Scala source

Run the following command.

make

Note: Some warnings are safe to ignore, like this: [warn] Multiple main classes detected.

1.4 Run mog-frontend

To run the testing site of mog-frontend (almost identical to Shogi Playground), you will need two command-line terminals.

  • Terminal 1

Run the following command to launch a local HTTP server.

make server
  • Terminal 2

Run the following command to open the testing URL on your default browser.

make local

Congratulations! Now you can play around Shogi Playground locally.

Note: Some features of Shogi Playground may access external servers such as Shogi Playground APIs (https://kifu.co). Please test considerably or isolate your environment from the Internet.

Note: If you update mog-core-scala code, you will have to modify build.sbt in the mog-frontend repository. Otherwise, sbt will download the latest source code from GitHub.

1.5 Tips

  • You may perform continuous building by the following command (sbt will watch source files and build automatically).
$ sbt
> ~test:fastOptJS
  • In tmux, ./scripts/tmux_start.sh will help automate your tasks.

2. Development Cycle

2.1 Fork the Repository

Fork appropriate repository (usually mog-frontend, sometimes mog-core-scala) to your GitHub account.

2.2 Update Code Locally

Create a feature branch in your develop environment.

2.3 Test Your Code Locally

In addition to manual testing, make sure to pass all unit tests (run make test) before creating a pull request.

There is no unit test in mog-playground.

2.4 Create Pull Request

Please create a pull request in the repository where the code exists.

See: Creating a pull request from a fork https://help.github.com/en/articles/creating-a-pull-request-from-a-fork

2.5 Code Review

Code review will be done by Admin.

2.6 Deployment

Deployment will be done by Admin.

In the mog-playground repository, run sbt publish.

Clone this wiki locally