= Fabric8 Planner

image:https://jenkins.cd.test.fabric8.io/job/fabric8-ui/job/fabric8-planner/job/master/badge/icon[Jenkins, link="https://jenkins.cd.test.fabric8.io/job/fabric8-ui/job/fabric8-planner/job/master/"] image:https://img.shields.io/npm/v/fabric8-planner.svg[npm, link="https://npmjs.com/package/fabric8-planner"] image:https://codecov.io/gh/fabric8-ui/fabric8-planner/branch/master/graph/badge.svg[Codecov.io, link="https://codecov.io/gh/fabric8-ui/fabric8-planner"] image:https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic%20release-b4d455.svg[Semantic Release, link="https://github.com/semantic-release/semantic-release"]

:icons: :toc: macro :toc-title: :toclevels: 1

toc::[]

== Overview Fabric8 Planner is a task planner and the issue tracker front-end for link:https://openshift.io/[openshift.io]. It uses the link:https://github.com/fabric8-services/fabric8-wit[Fabric8 Work Item Tracker] as the back-end.

The Planner project provides a component library which is used by other applications to provide a task planning front-end.

== Running the Planner

The Planner is available as an npm package. It can not be run by itself as it is an Angular component library.

However, for development and testing purpose, a minimal runtime environment is available in the link:runtime[runtime] directory. So you can run Planner either as a minimal Standalone component or as an Integrated component using an external webapp like the fabric8-ui. Typically, you would want to develop in the Standalone mode and test your changes in the Integrated mode.

=== Quickstart

The Planner build can be quickly run using the link:scripts/run-planner.sh[launcher script].

You can use the launcher script to run the Planner either as a Standalone component or as an Integrated component using an external webapp like the fabric8-ui.

• Without Docker: To run a minimal runtime implementation of the Planner using an in-memory mock database use:

[sh]

$ scripts/run-planner.sh --standalone

You can access the service on localhost:8080 + NOTE: To run the script on macOS, install gnu-getopt, run brew install gnu-getopt, and set it in your PATH: echo 'export PATH="/usr/local/opt/gnu-getopt/bin:$PATH"' >> ~/.zshrc.

• With Docker: To run the complete Planner stack using Docker Compose with link:https://github.com/fabric8-services/fabric8-wit[core], link:https://github.com/fabric8-services/fabric8-auth[auth] and their respective database setups use:

[sh]

docker-compose up

For detailed information on building and running Planner see link:docs/building_planner.adoc[Building the Planner Component Library] documentation.

== Useful Scripts and Tasks

The Planner delegates task running to gulp and allows parametric subtasks in the format of npm run <task> \-- --subtask which translates into gulp <task> --subtask which is then can be executed.

The scripts section of the link:package.json[package.json] file lists the main tasks i.e. build, clean & test. Following table lists the available npm scripts managed with gulp tasks, but to understand the routines triggered by the subtask parameters, please check out the link:gulpfile.js[gulpfile]:

[cols="1,1,3,4a", options="header"] |=== |Task |Subtask |Command |Description

.6+| Build

| [default] app v|npm run build or npm run build \-- --app | Builds the planner library

| [line-through]#image# v|npm run build \-- --image | Creates container image for the app

| release v|npm run build \-- --release | Publishes the library to *npm* registry

| [line-through]#tarball# v|npm run build \-- --tarball | Packs the library into a tarball

| [line-through]#validate# v|npm run build \-- --validate | Dry runs the build for validation

| watch v|npm run build \-- --watch | Rebuilds planner library on file changes

.7+| Clean

| [default] all v|npm run clean or npm run clean \-- --all | Fully resets the project

| cache v|npm run clean \-- --cache | Clears *npm* cache

| config v|npm run clean \-- --config | Resets app config & env_vars

| dist v|npm run clean \-- --dist | Removes the build artifacts

| images v|npm run clean \-- --images | Stops containers & removes the images

| modules v|npm run clean \-- --modules | Removes all *node* modules

| temp v|npm run clean \-- --temp | Removes temp files and artifacts

.3+| Tests

| unit v|npm run tests \-- --unit | Runs the unit tests

| [line-through]#func# v|npm run tests \-- --func | Runs the functional tests

| [line-through]#smok# v|npm run tests \-- --smok | Runs the smoke tests

4+| Commands with [line-through]#strikethroughs# aren't yet implemented.

|===

== Documentation The following documentation is available in the docs directory:

• link:docs/building_planner.adoc[Building the Planner]: Provides information on manually building the Planner in Standalone, Integrated, and Production environments.
• link:docs/technology_stack.adoc[Technology Stack]: Lists the the technology stack used by Planner.
• link:docs/testing.adoc[Testing]: Covers the tests you can run on Planner.

== Contributing

All contributions are welcome, if you want to contribute to this project, ensure you follow the link:CONTRIBUTING.adoc[Contribution Guidelines].