<commit_before>= Fabric8 Planner

[![Build Status](https://ci.centos.org/buildStatus/icon?job=devtools-fabric8-planner-build-master)](https://ci.centos.org/view/Devtools/job/devtools-fabric8-planner-build-master/)
[![Build Status](https://ci.centos.org/buildStatus/icon?job=devtools-fabric8-planner-npm-publish-build-master)](https://ci.centos.org/view/Devtools/job/devtools-fabric8-planner-npm-publish-build-master/)
image:https://codecov.io/gh/almighty/almighty-ui/branch/master/graph/badge.svg[Codecov.io,link="https://codecov.io/gh/almighty/almighty-ui"]

=== Fabric8 Planner is a currently an application planner and issue tracker front-end.
It uses https://github.com/almighty/almighty-core[Fabric8 Work Item Tracker] as the back-end.

If this is the first time you are starting the UI you need to run

----
$ npm install
----

If you trying to refresh your install you can run:

----
$ npm run reinstall
----

Start the app by executing the following.

----
$ npm start
----

If you wish to run the app with the in-memory dataset, you need to set an environment
variable "ENV" to "inmemory" and do a rebuild. The setting is stored inside the build,
changing the value back to unset or "development" (default for npm start) needs a rebuild
to take effect.

== Run All Checks

To run the linter, build validator, unit tests, and functional test use:

----
$ npm test
----


== Lint

To run the TypeScript and Angular 2 linter, use:

----
$ npm run lint
----

NOTE: They also run during the unit tests.

== Build Validation

To validate the webpack build, use:

----
$ npm run validate
----

NOTE: Validation also runs the unit tests.

== Unit Tests

To run the unit test, use:

----
$ npm run test:unit
----

To run the unit test in a watch mode so that they are rerun every time you save, use:

----
$ npm run watch:test
----

Unit (UI) tests are automatically executed on the PR(pull request) check process (using
`cico_run_tests.sh`) or on the release process (using `cico_build_deploy.sh`). To executed
these scripts from the development environment you can run the following script:

----
./run_unit_tests.sh
----

For unit testing, Jasmine, Karma, Webpack is used. There are unit tests available for
both services and UI components. There are `.spec.ts` files available in individual
component or service folder. Karma and Webpack config is written inside config directory
under root.

== Functional Tests

To run the functional test, use:

----
$ npm run test:func
----

Functional (UI) tests are automatically executed on the PR check process (using
`cico_run_tests.sh`) or on the release process (using `cico_build_deploy.sh`) but
can also be executed from the development environment by invoking the following command:

----
./run_functional_tests.sh
----

External resources are mocked. A Java JRE, ncat and fuser have to be available on the
system (see Dockerfile.builder for details on the required packages when building on
Fedora/CentOS). PhantomJS will be used as the browser engine by default. This can be
changed by adding/modifying browser capabilities in `protractor.config.js`.

Test specs for functional tests are residing in `src/tests`.

== Production Build

To generate production build, set the API URL and run `npm` command as give below:

----
export API_URL="http://api.example.org/api/"
npm run build:prod
----

The build output will be under `dist` directory.

To create docker image, run this command immediately after the previous command:

----
docker build -t almighty-ui-deploy -f Dockerfile.deploy .
----

== Building the NPM Library

To build the NPM library, use this command:

---
export API_URL="http://api.example.org/api/"
npm run build:npm
---

== Library Build

To build the Planner as a npm library, use gulp:

---
gulp build
---

The created library is located in `dist-library`. To publish it to npm:

---
cd dist-library
npm publish
---

You may need to login first on the npmjs service.

[[continuous-delivery-semantic-relases]]
Continuous Delivery & Semantic Relases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In fabric8-planner we use the
https://github.com/semantic-release/semantic-release[semantic-release
plugin]. That means that all you have to do is use the AngularJS Commit
Message Conventions (documented below). Once the PR is merged, a new
release will be automatically published to npmjs.com and a release tag
created on github. The version will be updated following semantic
versionning rules.

[[commit-message-format]]
Commit Message Format
^^^^^^^^^^^^^^^^^^^^^

A commit message consists of a *header*, *body* and *footer*. The header
has a *type*, *scope* and *subject*:

....
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
....

The *header* is mandatory and the *scope* of the header is optional.

Any line of the commit message cannot be longer 100 characters! This
allows the message to be easier to read on GitHub as well as in various
git tools.

[[revert]]
Revert
^^^^^^

If the commit reverts a previous commit, it should begin with `revert:`,
followed by the header of the reverted commit. In the body it should
say: `This reverts commit <hash>.`, where the hash is the SHA of the
commit being reverted.

[[type]]
Type
^^^^

If the prefix is `feat`, `fix` or `perf`, it will always appear in the
changelog.

Other prefixes are up to your discretion. Suggested prefixes are `docs`,
`chore`, `style`, `refactor`, and `test` for non-changelog related
tasks.

[[scope]]
Scope
^^^^^

The scope could be anything specifying place of the commit change. For
example `$location`, `$browser`, `$compile`, `$rootScope`, `ngHref`,
`ngClick`, `ngView`, etc…

[[subject]]
Subject
^^^^^^^

The subject contains succinct description of the change:

* use the imperative, present tense: ``change'' not ``changed'' nor
``changes''
* don’t capitalize first letter
* no dot (.) at the end

[[body]]
Body
^^^^

Just as in the *subject*, use the imperative, present tense: ``change''
not ``changed'' nor ``changes''. The body should include the motivation
for the change and contrast this with previous behavior.

[[footer]]
Footer
^^^^^^

The footer should contain any information about *Breaking Changes* and
is also the place to reference GitHub issues that this commit *Closes*.

*Breaking Changes* should start with the word `BREAKING CHANGE:` with a
space or two newlines. The rest of the commit message is then used for
this.

A detailed explanation can be found in this
https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#[document].

Based on
https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit

[[examples]]
Examples
^^^^^^^^

Appears under ``Features'' header, pencil subheader:

....
feat(pencil): add 'graphiteWidth' option
....

Appears under ``Bug Fixes'' header, graphite subheader, with a link to
issue #28:

....
fix(graphite): stop graphite breaking when width < 0.1

Closes #28
....

Appears under ``Performance Improvements'' header, and under ``Breaking
Changes'' with the breaking change explanation:

....
perf(pencil): remove graphiteWidth option

BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reason.
....

The following commit and commit `667ecc1` do not appear in the changelog
if they are under the same release. If not, the revert commit appears
under the ``Reverts'' header.

....
revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
....

[[commitizen---craft-valid-commit-messages]]
Commitizen - craft valid commit messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Commitizen helps you craft correct commit messages. Install it using
`npm install commitizen -g`. Then run `git cz` rather than `git commit`.

[[validate-commit-msg---validate-commit-messages]]
Validate-commit-msg - validate commit messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The validate-commit-msg githook checks for invalid commit messages.
<commit_msg>docs: argh, this is adoc not md!<commit_after>= Fabric8 Planner

image:https://ci.centos.org/buildStatus/icon?job=devtools-fabric8-planner-build-master[Jenkins,link="https://ci.centos.org/view/Devtools/job/devtools-fabric8-planner-build-master/lastBuild/"]
image:https://ci.centos.org/buildStatus/icon?job=devtools-fabric8-planner-npm-publish-build-master[Jenkins,link="https://ci.centos.org/view/Devtools/job/devtools-fabric8-planner-npm-publish-build-master/lastBuild/"]
image:https://codecov.io/gh/almighty/almighty-ui/branch/master/graph/badge.svg[Codecov.io,link="https://codecov.io/gh/almighty/almighty-ui"]

=== Fabric8 Planner is a currently an application planner and issue tracker front-end.
It uses https://github.com/almighty/almighty-core[Fabric8 Work Item Tracker] as the back-end.

If this is the first time you are starting the UI you need to run

----
$ npm install
----

If you trying to refresh your install you can run:

----
$ npm run reinstall
----

Start the app by executing the following.

----
$ npm start
----

If you wish to run the app with the in-memory dataset, you need to set an environment
variable "ENV" to "inmemory" and do a rebuild. The setting is stored inside the build,
changing the value back to unset or "development" (default for npm start) needs a rebuild
to take effect.

== Run All Checks

To run the linter, build validator, unit tests, and functional test use:

----
$ npm test
----


== Lint

To run the TypeScript and Angular 2 linter, use:

----
$ npm run lint
----

NOTE: They also run during the unit tests.

== Build Validation

To validate the webpack build, use:

----
$ npm run validate
----

NOTE: Validation also runs the unit tests.

== Unit Tests

To run the unit test, use:

----
$ npm run test:unit
----

To run the unit test in a watch mode so that they are rerun every time you save, use:

----
$ npm run watch:test
----

Unit (UI) tests are automatically executed on the PR(pull request) check process (using
`cico_run_tests.sh`) or on the release process (using `cico_build_deploy.sh`). To executed
these scripts from the development environment you can run the following script:

----
./run_unit_tests.sh
----

For unit testing, Jasmine, Karma, Webpack is used. There are unit tests available for
both services and UI components. There are `.spec.ts` files available in individual
component or service folder. Karma and Webpack config is written inside config directory
under root.

== Functional Tests

To run the functional test, use:

----
$ npm run test:func
----

Functional (UI) tests are automatically executed on the PR check process (using
`cico_run_tests.sh`) or on the release process (using `cico_build_deploy.sh`) but
can also be executed from the development environment by invoking the following command:

----
./run_functional_tests.sh
----

External resources are mocked. A Java JRE, ncat and fuser have to be available on the
system (see Dockerfile.builder for details on the required packages when building on
Fedora/CentOS). PhantomJS will be used as the browser engine by default. This can be
changed by adding/modifying browser capabilities in `protractor.config.js`.

Test specs for functional tests are residing in `src/tests`.

== Production Build

To generate production build, set the API URL and run `npm` command as give below:

----
export API_URL="http://api.example.org/api/"
npm run build:prod
----

The build output will be under `dist` directory.

To create docker image, run this command immediately after the previous command:

----
docker build -t almighty-ui-deploy -f Dockerfile.deploy .
----

== Building the NPM Library

To build the NPM library, use this command:

---
export API_URL="http://api.example.org/api/"
npm run build:npm
---

== Library Build

To build the Planner as a npm library, use gulp:

---
gulp build
---

The created library is located in `dist-library`. To publish it to npm:

---
cd dist-library
npm publish
---

You may need to login first on the npmjs service.

[[continuous-delivery-semantic-relases]]
Continuous Delivery & Semantic Relases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In fabric8-planner we use the
https://github.com/semantic-release/semantic-release[semantic-release
plugin]. That means that all you have to do is use the AngularJS Commit
Message Conventions (documented below). Once the PR is merged, a new
release will be automatically published to npmjs.com and a release tag
created on github. The version will be updated following semantic
versionning rules.

[[commit-message-format]]
Commit Message Format
^^^^^^^^^^^^^^^^^^^^^

A commit message consists of a *header*, *body* and *footer*. The header
has a *type*, *scope* and *subject*:

....
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
....

The *header* is mandatory and the *scope* of the header is optional.

Any line of the commit message cannot be longer 100 characters! This
allows the message to be easier to read on GitHub as well as in various
git tools.

[[revert]]
Revert
^^^^^^

If the commit reverts a previous commit, it should begin with `revert:`,
followed by the header of the reverted commit. In the body it should
say: `This reverts commit <hash>.`, where the hash is the SHA of the
commit being reverted.

[[type]]
Type
^^^^

If the prefix is `feat`, `fix` or `perf`, it will always appear in the
changelog.

Other prefixes are up to your discretion. Suggested prefixes are `docs`,
`chore`, `style`, `refactor`, and `test` for non-changelog related
tasks.

[[scope]]
Scope
^^^^^

The scope could be anything specifying place of the commit change. For
example `$location`, `$browser`, `$compile`, `$rootScope`, `ngHref`,
`ngClick`, `ngView`, etc…

[[subject]]
Subject
^^^^^^^

The subject contains succinct description of the change:

* use the imperative, present tense: ``change'' not ``changed'' nor
``changes''
* don’t capitalize first letter
* no dot (.) at the end

[[body]]
Body
^^^^

Just as in the *subject*, use the imperative, present tense: ``change''
not ``changed'' nor ``changes''. The body should include the motivation
for the change and contrast this with previous behavior.

[[footer]]
Footer
^^^^^^

The footer should contain any information about *Breaking Changes* and
is also the place to reference GitHub issues that this commit *Closes*.

*Breaking Changes* should start with the word `BREAKING CHANGE:` with a
space or two newlines. The rest of the commit message is then used for
this.

A detailed explanation can be found in this
https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#[document].

Based on
https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit

[[examples]]
Examples
^^^^^^^^

Appears under ``Features'' header, pencil subheader:

....
feat(pencil): add 'graphiteWidth' option
....

Appears under ``Bug Fixes'' header, graphite subheader, with a link to
issue #28:

....
fix(graphite): stop graphite breaking when width < 0.1

Closes #28
....

Appears under ``Performance Improvements'' header, and under ``Breaking
Changes'' with the breaking change explanation:

....
perf(pencil): remove graphiteWidth option

BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reason.
....

The following commit and commit `667ecc1` do not appear in the changelog
if they are under the same release. If not, the revert commit appears
under the ``Reverts'' header.

....
revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
....

[[commitizen---craft-valid-commit-messages]]
Commitizen - craft valid commit messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Commitizen helps you craft correct commit messages. Install it using
`npm install commitizen -g`. Then run `git cz` rather than `git commit`.

[[validate-commit-msg---validate-commit-messages]]
Validate-commit-msg - validate commit messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The validate-commit-msg githook checks for invalid commit messages.

{'fraction_non_alphanumeric': 0.12248062015503876, 'fraction_numerical': 0.007565891472868217, 'mean_word_length': 4.173564324671158, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 19, 'https://': 20, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2423981', 'n_tokens_mistral': 4920, 'n_tokens_neox': 4651, 'n_words': 2006}