Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/fabric8-services/fabric8-wit

wit stands for Work Item Tracker
https://github.com/fabric8-services/fabric8-wit

goa golang jsonapi microservice webservice

Last synced: 3 months ago
JSON representation

wit stands for Work Item Tracker

Lists

README 

        
= Fabric8 Work Item Tracker

:toc:

:toc-placement: preamble

:sectnums:

:experimental:



image:https://ci.centos.org/buildStatus/icon?job=devtools-fabric8-wit-build-master[Jenkins,link="https://ci.centos.org/view/Devtools/job/devtools-fabric8-wit-build-master/lastBuild/"]

image:https://goreportcard.com/badge/github.com/fabric8-services/fabric8-wit[Go Report Card, link="https://goreportcard.com/report/github.com/fabric8-services/fabric8-wit"]

image:https://godoc.org/github.com/fabric8-services/fabric8-wit?status.png[GoDoc,link="https://godoc.org/github.com/fabric8-services/fabric8-wit"]

image:https://codecov.io/gh/fabric8-services/fabric8-wit/branch/master/graph/badge.svg[Codecov.io,link="https://codecov.io/gh/fabric8-services/fabric8-wit"]



Work Items describe and keep track of work that needs to be done. A user can be assigned to a Work Item. Each Work Item must be attached to a Collaboration Space and an Area (assigned by default). This can be used to model bugs, tasks, features, ideas, and more.



== Building from source [[building]]



The following guide is mainly targeted towards a Linux or Mac OSX development

machine. If you are on Windows, we recommend to take a look at

link:docs/development/getting-started-win.adoc[Getting started with fabric8-wit development on Windows].



=== Prerequisites [[prerequisites]]



You need to install:



* `go` (>= v1.8)

* `git`

* `mercurial`

* `make`



==== Check your Go version [[check-go-version]]



Run the following command to find out your Go version.



----

$ go version

----



*You must at least have Go version 1.8.*



See <> to see an explanaition on how we deal with

dependencies.



==== Install dep [[dep-setup]]



This project uses https://github.com/golang/dep[dep] as a package manager for Go.

Running the `make deps` command will install `dep` in `$GOPATH/bin` if it's not already available on your system.



=== Get the code [[get-the-code]]



Assuming you have Go installed and configured (have `$GOPATH` setup and

pointing to a single directory) here is how to build.



Check out the code



----

$ git clone https://github.com/fabric8-services/fabric8-wit $GOPATH/src/github.com/fabric8-services/fabric8-wit

----



=== Build [[build]]



Like most other projects, this one depends on various other projects that need

to be downloaded.



We also generate some code from design files that shall make it into our

final artifacts.



To fetch the dependencies, generate code and finally build the project you can

type `make` in a freshly clone repository of this project.



----

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit

$ make

----



==== Special make targets



There is no need to fetch the dependencies, or re-generate code every time you

want to compile. That's why we offer special `make` targets for these topics:



 * <>

 * <>

 * <>

 * <>

 * <>

 * <>



===== Fetch dependencies [[fetch-dependencies]]



This will download all the dependencies for this project inside a directory

called `vendor`. This way we can ensure that every developer and our CI system

is using the same version.



----

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit

$ make deps

----



For dependency management of `go` packages we use https://github.com/golang/dep[`dep`].

The file `Gopkg.toml` contains all dependencies. If you want to

understand the format for this file, look link:https://golang.github.io/dep/docs/Gopkg.toml.html[here].



===== Generate GOA sources [[generate-code]]



You need to run this command if you just checked out the code and later if

you've modified the designs.



----

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit

$ make generate

----



===== Build [[build]]



If you want to just build the ALM server and client, run `make build`.



----

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit

$ make build

----



===== Clean [[clean]]



This removes all downloaded dependencies, all generated code and compiled

artifacts.



----

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit

$ make clean

----



===== Tests [[test]]



Here's how to run all available tests. All tests will check all Go packages

except those in the `vendor/` directory.

Make sure you have docker and docker-compose available.



Setting up test environment - `make integration-test-env-prepare`



Tear test environment down - `make integration-test-env-tear-down`



[horizontal]

unit-tests::

Unit tests have the minimum requirement on time and environment setup.

+

----

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit

$ make test-unit

----



integration-tests::

Integration tests demand more setup (i.e. the PostgreSQL DB must be already

running) and probably time. We recommend that you use `docker-compose up -d db`.

+

----

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit

$ make test-integration

----



all::

To run both, the unit and the integration tests you can run

+

----

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit

$ make test-all

----



===== Coverage [[coverage]]



To visualize the coverage of unit, integration, or all tests you can run these

commands:



 * `$ make coverage-unit`

 * `$ make coverage-integration`

 * `$ make coverage-all`



NOTE: If the tests (see <>) have not yet run, or if the sources have changed

since the last time the tests ran, they will be re-run to produce up to date

coverage profiles.



Each of the above tests (see <>) produces a coverage profile by default.

Those coverage files are available under



----

tmp/coverage//coverage..mode-

----



Here's how the  expand



[horizontal]

``::

something like `github.com/fabric8-services/fabric8-wit/models`



``::

`unit` or `integration`



``::

Sets the mode for coverage analysis for the packages being tested.

Possible values for `` are *set* (the default), *count*, or *atomic* and

they directly relate to the output of `go test --help`.

 * *set*: bool: does this statement run?

 * *count*: int: how many times does this statement run?

 * *atomic*: int: count, but correct in multithreaded tests; significantly more

   expensive.



In addition to all individual coverage information for each package, we also

create three more files:



[horizontal]

`tmp/coverage.unit.mode-`::

This file collects all the coverage profiles for all *unit* tests.



`tmp/coverage.integration.mode-`::

This file collects all the coverage profiles for all *integration* tests.



`tmp/coverage.mode-`::

This file is the merge result of the two afore mentioned files and thus gives

coverage information for all tests.



== Build through minishift



There is a separate documentation for https://github.com/fabric8-services/fabric8-wit/blob/master/minishift/README.adoc[building WIT using minishift]



== Configuration file



If no configuration file is specified when the core is started, these are the defaults.



[source,yaml]

.config.yaml

----

#------------------------

# Postgres configuration

#------------------------



postgres.host: localhost

postgres.port: 5432

postgres.user: postgres

postgres.password: mysecretpassword

postgres.database: postgres

postgres.sslmode: disable

# The amount of time in seconds before the connection times out

postgres.connection.timeout: 5

# Duration to wait before trying to connect again

postgres.connection.retrysleep: 1s



#------------------------

# HTTP configuration

#------------------------



http.address: 0.0.0.0:8080



#------------------------

# Misc.

#------------------------



# Enable development related features, e.g. token generation endpoint

developer.mode.enabled: false



# Whether you want to create the common work item types such as bug, feature, ...

populate.commontypes: true



# -----------------------------

# Authentication configuration

# -----------------------------



token.privatekey : >

                    -----BEGIN RSA PRIVATE KEY-----

                    MIIEpQIBAAKCAQEAnwrjH5iTSErw9xUptp6QSFoUfpHUXZ+PaslYSUrpLjw1q27O

                    DSFwmhV4+dAaTMO5chFv/kM36H3ZOyA146nwxBobS723okFaIkshRrf6qgtD6coT

                    HlVUSBTAcwKEjNn4C9jtEpyOl+eSgxhMzRH3bwTIFlLlVMiZf7XVE7P3yuOCpqkk

                    2rdYVSpQWQWKU+ZRywJkYcLwjEYjc70AoNpjO5QnY+Exx98E30iEdPHZpsfNhsjh

                    9Z7IX5TrMYgz7zBTw8+niO/uq3RBaHyIhDbvenbR9Q59d88lbnEeHKgSMe2RQpFR

                    3rxFRkc/64Rn/bMuL/ptNowPqh1P+9GjYzWmPwIDAQABAoIBAQCBCl5ZpnvprhRx

                    BVTA/Upnyd7TCxNZmzrME+10Gjmz79pD7DV25ejsu/taBYUxP6TZbliF3pggJOv6

                    UxomTB4znlMDUz0JgyjUpkyril7xVQ6XRAPbGrS1f1Def+54MepWAn3oGeqASb3Q

                    bAj0Yl12UFTf+AZmkhQpUKk/wUeN718EIY4GRHHQ6ykMSqCKvdnVbMyb9sIzbSTl

                    v+l1nQFnB/neyJq6P0Q7cxlhVj03IhYj/AxveNlKqZd2Ih3m/CJo0Abtwhx+qHZp

                    cCBrYj7VelEaGARTmfoIVoGxFGKZNCcNzn7R2ic7safxXqeEnxugsAYX/UmMoq1b

                    vMYLcaLRAoGBAMqMbbgejbD8Cy6wa5yg7XquqOP5gPdIYYS88TkQTp+razDqKPIU

                    hPKetnTDJ7PZleOLE6eJ+dQJ8gl6D/dtOsl4lVRy/BU74dk0fYMiEfiJMYEYuAU0

                    MCramo3HAeySTP8pxSLFYqJVhcTpL9+NQgbpJBUlx5bLDlJPl7auY077AoGBAMkD

                    UpJRIv/0gYSz5btVheEyDzcqzOMZUVsngabH7aoQ49VjKrfLzJ9WznzJS5gZF58P

                    vB7RLuIA8m8Y4FUwxOr4w9WOevzlFh0gyzgNY4gCwrzEryOZqYYqCN+8QLWfq/hL

                    +gYFYpEW5pJ/lAy2i8kPanC3DyoqiZCsUmlg6JKNAoGBAIdCkf6zgKGhHwKV07cs

                    DIqx2p0rQEFid6UB3ADkb+zWt2VZ6fAHXeT7shJ1RK0o75ydgomObWR5I8XKWqE7

                    s1dZjDdx9f9kFuVK1Upd1SxoycNRM4peGJB1nWJydEl8RajcRwZ6U+zeOc+OfWbH

                    WUFuLadlrEx5212CQ2k+OZlDAoGAdsH2w6kZ83xCFOOv41ioqx5HLQGlYLpxfVg+

                    2gkeWa523HglIcdPEghYIBNRDQAuG3RRYSeW+kEy+f4Jc2tHu8bS9FWkRcsWoIji

                    ZzBJ0G5JHPtaub6sEC6/ZWe0F1nJYP2KLop57FxKRt0G2+fxeA0ahpMwa2oMMiQM

                    4GM3pHUCgYEAj2ZjjsF2MXYA6kuPUG1vyY9pvj1n4fyEEoV/zxY1k56UKboVOtYr

                    BA/cKaLPqUF+08Tz/9MPBw51UH4GYfppA/x0ktc8998984FeIpfIFX6I2U9yUnoQ

                    OCCAgsB8g8yTB4qntAYyfofEoDiseKrngQT5DSdxd51A/jw7B8WyBK8=

                    -----END RSA PRIVATE KEY-----



token.publickey : >

                    -----BEGIN PUBLIC KEY-----

                    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnwrjH5iTSErw9xUptp6Q

                    SFoUfpHUXZ+PaslYSUrpLjw1q27ODSFwmhV4+dAaTMO5chFv/kM36H3ZOyA146nw

                    xBobS723okFaIkshRrf6qgtD6coTHlVUSBTAcwKEjNn4C9jtEpyOl+eSgxhMzRH3

                    bwTIFlLlVMiZf7XVE7P3yuOCpqkk2rdYVSpQWQWKU+ZRywJkYcLwjEYjc70AoNpj

                    O5QnY+Exx98E30iEdPHZpsfNhsjh9Z7IX5TrMYgz7zBTw8+niO/uq3RBaHyIhDbv

                    enbR9Q59d88lbnEeHKgSMe2RQpFR3rxFRkc/64Rn/bMuL/ptNowPqh1P+9GjYzWm

                    PwIDAQAB

                    -----END PUBLIC KEY-----



# ----------------------------

# Github OAuth2 configuration

# ----------------------------



github.client.id : 875da0d2113ba0a6951d

github.secret : 2fe6736e90a9283036a37059d75ac0c82f4f5288



----



Although this is a YAML file, we highly suggest to stick to this rather lenghty notation instead of nesting structs.



To override configuration values using environment variables, use the prefix

`F8_` and replace the dots in the variables names with underscores.



For example to override `postgres.password`, set the environment variable `F8_POSTGRES_PASSWORD` to the value of you liking.



NOTE: config.yaml is *not* processed by default. In order to use it, the following environment variable must be set `export F8_CONFIG_FILE_PATH="config.yaml"`



NOTE: Environment variables override the default values and the ones you've set in your config file.



==== Development



Only files `+./*.go+`, `+./design/*.go+`, `+./models/*.go+` and `+./tool/wit-cli/main.go+` should be edited.



These files and directory are generated:



 * `./app/`

 * `./assets/js/`

 * `./client/`

 * `./swagger/`

 * `./tool/cli/`

 * `./bindata_asstfs.go`



== Developer setup



Start up dependent docker services using `docker-compose` and runs auto reload on source change tool `fresh`.



----

$ cd $GOPATH/src/github.com/fabric8-services/fabric8-wit

$ make dev

----



The above steps start the API Server on port 8080.



Test out the build by executing CLI commands in a different terminal.



NOTE: The CLI needs the API Server which was started on executing `make dev`  to be up and running. Please do not kill the process. Alternatively if you haven't run `make dev` you could just start the server by running `./bin/alm`.



* Generate a token for future use.

----

$ bin/wit-cli generate login -H localhost:8080 --pp

----



You should get access_token in response, set it as env to ease future call:

----

$ export KEY=

----



* Create a space

----

$ bin/wit-cli create space -H localhost:8080 --key $KEY --payload '{"data": {"name": "MY_SPACE","path": "","attributes": {"name": "MY_SPACE","description": "description"},"type": "spaces","privateSpace": false}}'

----

Note the spaceID to be used in next request.



* Create a workitem for your newly created space

----

$ bin/wit-cli create workitems -H localhost:8080 --key $KEY --spaceID 564a1296-887e-47fe-9e56-40a39995f585 --payload '{"data":{"attributes":{"system.title":"test","system.description":"","system.state":"New"},"relationships":{"baseType":{"data":{"id":"2c169431-a55d-49eb-af74-cc19e895356f","type":"workitemtypes"}}},"type":"workitems"}}

----

where baseType in the payload refer to a work item type.



* List all workitems for a given space:

----

$ bin/wit-cli list workitems -H localhost:8080 --pp --spaceID 564a1296-887e-47fe-9e56-40a39995f585

----



=== Reset Database



The database are kept in a docker container that gets reused between restarts. Thus restarts will not clear out the database.



To clear out the database kill the database like this:



----

$ docker kill fabric8wit_db_1 && docker rm fabric8wit_db_1

----



In case you have mulitple `fabric8*` running use `docker ps` to locate the container name.



== Debugging [[debug]]



System defined Work Item Types are



 * userstory

 * valueproposition

 * fundamental

 * experience

 * feature

 * bug



Use any one of above to create Work Item based on that type.

Following example creates a Work Item of type `userstory`

----

$ ./bin/wit-cli create workitem --key "" --payload '{ "data": { "attributes": { "system.owner": "tmaeder", "system.state": "open", "system.title": "Example of an Epic", "version": "1" }, "relationships": { "baseType": { "data": { "id": "Epic", "type": "workitemtypes" } } }, "type": "workitems" } }' -H localhost:8080

----



In response you should get ID of created item, using that you can retrieve the work item.



----

$ ./bin/wit-cli show workitem --id  -H localhost:8080 --pp

----



== Swagger API



A browsable documentation for our API is available with http://swagger.goa.design/?url=github.com%2Ffabric8-services%2Ffabric8-wit%2Fdesign[goa Swagger Generator]. It reflects the latest state of the master branch.



== Prod preview setup



In order to setup wit to work against link:https://prod-preview.openshift.io/[prod preview] the following environment variables must be set:



* `export F8_DEVELOPER_MODE_ENABLED=1`

* `export F8_OPENSHIFT_TENANT_MASTERURL="https://console.free-stg.openshift.com/"`

* `export F8_KEYCLOAK_REALM="fabric8"`

* `export F8_CONFIG_FILE_PATH="config.yaml"`



Also, `F8_TENANT_SERVICEURL` env var must be set and point to the prod-preview link:https://github.com/fabric8-services/fabric8-tenant[fabric8-tenant] endpoint.

However, there is no publicly available route for it and one should `oc login` to the prod-preview OpenShift Dedicated cluster and use

link:https://docs.openshift.com/enterprise/3.0/dev_guide/port_forwarding.html[port forwarding] for fabric8-tenant pod:



----

$ oc port-forward  :8080

----



* `export F8_TENANT_SERVICEURL="http://localhost:/"`



== che-starter setup



link:https://github.com/redhat-developer/che-starter[che-starter] endpoint can be configure via the following environment variable:



* `export F8_CHESTARTERURL="http://localhost:10000/"`