top
(README.adoc)
= ALMighty Core

:toc:
:sectnums:
:experimental:

image:https://goreportcard.com/badge/github.com/almighty/almighty-core[Go Report Card, link="https://goreportcard.com/report/github.com/almighty/almighty-core"]
image:https://godoc.org/github.com/almighty/almighty-core?status.png[GoDoc,link="https://godoc.org/github.com/almighty/almighty-core"]

== 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 almighty-core development on Windows].

=== Prerequisites [[prerequisites]]

You need to install:

* `go` (>= v1.6)
* `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.6. Our code uses a code generation
tool called goa and it doesn't play nice together with Go 1.5.*

Ensure the environment variable `GO15VENDOREXPERIMENT`
is set, for example by running `export GO15VENDOREXPERIMENT=1`.
In Go `1.6` it is enabled by default and in Go `1.7` it is always enabled
without the ability to turn it off.

If set, the link:https://github.com/golang/go/wiki/PackageManagementTools#go15vendorexperiment[`GO15VENDOREXPERIMENT`]
variable tells `go` to look for dependencies not only in the `GOPATH` (as usual)
but also in a `vendor` directory located in the source directory.

See <<fetch-dependencies>> to see an explanaition on how we deal with
dependencies.

==== Install glide [[glide-setup]]

This project uses link:https://glide.sh/[glide] as a package manager for Go.

To install glide, go to the
link:https://github.com/Masterminds/glide/releases[release page] and download
the newest binary for your operating system.

Unpack the archive that you've downloaded and place the `glide` executable
somewhere so that it is in your `PATH`.

To check if everything is working, type `glide --version` in a terminal.

----
$ glide --version
glide version v0.11.0
----

Try to use at least version `0.11.0` as we haven't tested another version.

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

Assuming you have Go installed and configured (have `$GOPATH` setup) here is
how to build.

Check out the code

----
$ git clone https://github.com/almighty/almighty-core $GOPATH/src/github.com/almighty/almighty-core
----

=== 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/almighty/almighty-core
$ 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>>
 * <<generate-code>>
 * <<build>>
 * <<clean>>
 * <<test>>
 * <<coverage>>

===== 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/almighty/almighty-core
$ make deps
----

For dependency management of `go` packages we use `glide`.
The file `glide.yaml` contains all dependencies.
It is not suggested that you edit the file by hand but if you want to
understand the format for this file, look link:https://glide.readthedocs.io/en/latest/glide.yaml/[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/almighty/almighty-core
$ make generate
----

===== Build [[build]]

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

----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ make build
----

===== Clean [[clean]]

This removes all downloaded dependencies, all generated code and compiled
artifacts.

----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ 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.

[horizontal]
unit-tests::
Unit tests have the minimum requirement on time and environment setup.
+
----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ make test-unit
----

integration-tests::
Integration tests demand more setup (i.e. the PostgreSQL DB must be already
running) and probably time.
+
----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ make test-integration
----

all::
To run both, the unit and the integration tests you can run
+
----
$ cd $GOPATH/src/github.com/almighty/almighty-core
$ 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 <<test>>) 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 <<test>>) produces a coverage profile by default.
Those coverage files are available under

----
tmp/coverage/<package>/coverage.<test>.mode-<mode>
----

Here's how the <placeholders> expand

[horizontal]
`<package>`::
something like `github.com/almighty/almighty-core/models`

`<test>`::
`unit` or `integration`

`<mode>`::
Sets the mode for coverage analysis for the packages being tested.
Possible values for `<mode>` 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-<mode>`::
This file collects all the coverage profiles for all *unit* tests.

`tmp/coverage.integration.mode-<mode>`::
This file collects all the coverage profiles for all *integration* tests.

`tmp/coverage.mode-<mode>`::
This file is the merge result of the two afore mentioned files and thus gives
coverage information for all tests.

==== Development

Only files `+./*.go+`, `+./design/*.go+`, `+./models/*.go+` and `+./tool/alm-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/almighty/almighty-core
$ 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`.

Create a work item.

----
$ ./bin/alm-cli create workitem --payload '{"type": "1" , "name": "some name", "fields": { "system.owner": "tmaeder", "system.state": "open" }}' -H localhost:8080
----

Retrieve the work item.

----
$ ./bin/alm-cli show workitem --id 1 -H localhost:8080
----

== Debugging [[debug]]

This section shows how to install a Go debugger
(link:https://github.com/derekparker/delve:[delve]) and how to actually do some
debugging from a terminal.

For somebody coming from a C/C++ background this should feed very familiar as
the GNU Debugger or GDB command line interface has similar commands.
The following table illustrates just a few of the similarities.

.Small comparison between GNU Debugger (gdb) and Go Debugger (dlv) commands
|===
|Function | GNU Debugger | Go debugger (dlv)

|Connect to a running program
|`gdb attach <PID>`
|`dlv attach <PID>`

|Set a breakpoint
|`gdb break <function>`
|`dlv break <package>.<function>`

|Continue after hitting a breakpoint or attaching to a program
|`gdb continue`
|`dlv continue`

|Show a backtrace for the current location
|`gdb bt`
|`dlv bt`

|===

More commands can be found in the
link:https://github.com/derekparker/delve/tree/master/Documentation/cli#commands[Delve documentation].

=== Install debugger

Install the link:https://github.com/derekparker/delve:[delve] debugger by running:

----
$ go get github.com/derekparker/delve/cmd/dlv
----

This will create the file `$GOPATH/bin/dlv` so in order to run the `dlv`
executable from anywhere, make sure you have `$GOPATH/bin` in your `$PATH`.

link:https://github.com/derekparker/delve/tree/master/Documentation/installation:[Here]
are instructions to install delve on different platforms.

=== Example debugging

In this example we'll debug a running ALM server using delve and set a breakpoint
on the function `WorkitemController.Show`.

NOTE: To see other ways to run `dlv`, see the link:https://github.com/derekparker/delve/blob/master/Documentation/usage/dlv.md#dlv[usage page].

Let's assume the binary `./bin/alm` is running.

==== Attach to program

To link:https://github.com/derekparker/delve/blob/master/Documentation/usage/dlv_attach.md#dlv-attach[*attach*]
the debugger to your running almight-core server,run:

----
$ dlv attach $(pidof ./bin/alm)
----

The will bring you into the delve shell which looks like this:

----
Type 'help' for list of commands.
(dlv)
----

The `./bin/alm` program is *paused* right now. Once we've set a breakpoint we will
let it run again.

==== Set breakpoint

Now, set the link:https://github.com/derekparker/delve/tree/master/Documentation/cli#break[*breakpoint*]
on the on the `WorkitemController.Show` function that is defined in `workitem.go`:

----
(dlv) break WorkitemController.Show
----

As mentioned before the almighty-core server is paused and we need to bring it
back into a *run* state. To do this, we let the program
link:https://github.com/derekparker/delve/tree/master/Documentation/cli#continue[*continue*]:

----
(dlv) continue
----

==== Trigger breakpoint

Open another shell and fetch an existing workitem using curl:

----
$ curl http://localhost:8080/api/workitems/1
----

(Replace the `1` with an existing workitem ID if needed)

Now, your debugger shell show something like this:

----
> main.(*WorkitemController).Show() /tmp/go/src/github.com/almighty/almighty-core/workitem.go:30 (hits goroutine(11):1 total:3) (PC: 0x405633)
(dlv)
----

The program is *paused* again for you to inspect it and the curl command
has not returned yet.

==== Backtrace

To show a link:https://github.com/derekparker/delve/tree/master/Documentation/cli#stack[backtrace] of how we got here in terms of stack frames, run:

----
(dlv) bt
----

The output might look similar to this but it can change over time and as
development goes on:

----
0  0x0000000000405633 in main.(*WorkitemController).Show
   at /tmp/go/src/github.com/almighty/almighty-core/workitem.go:30
1  0x0000000000520014 in github.com/almighty/almighty-core/app.MountWorkitemController.func3
   at /tmp/go/src/github.com/almighty/almighty-core/app/controllers.go:222
2  0x00000000005202fe in github.com/almighty/almighty-core/app.handleWorkitemOrigin.func1
   at /tmp/go/src/github.com/almighty/almighty-core/app/controllers.go:257
3  0x0000000000540868 in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa.(*Controller).MuxHandler.func1.1
   at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/service.go:250
4  0x00000000005d6d3e in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware.Recover.func1.1
   at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware/recover.go:37
5  0x00000000005d3b9c in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware.ErrorHandler.func1.1
   at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware/error_handler.go:19
6  0x00000000005d5649 in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware.LogRequest.func1.1
   at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware/log_request.go:65
7  0x00000000005d7229 in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware.RequestIDWithHeaderAndLengthLimit.func1.1
   at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware/request_id.go:63
8  0x000000000054192c in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa.(*Controller).MuxHandler.func1
   at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/service.go:283
9  0x000000000053faf9 in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa.(*mux).Handle.func1
   at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/mux.go:57
10  0x000000000076c3c2 in github.com/almighty/almighty-core/vendor/github.com/dimfeld/httptreemux.(*TreeMux).ServeHTTP
   at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/dimfeld/httptreemux/router.go:247
----

The first incrementing number on every second line stands for the number of the
stackframe. Stackframe *0* is one where we set the breakpoint earlier.

==== Continue with normal processing

While there are many interesting ways to inspect your program using the *delve*
debugger, we will instead let our program *continue* to run and thereby proceed
with delivering the workitem to the curl command.

----
(dlv) continue
----

Check the shell in which you ran the curl command to see if you have go a result.

==== Exit debugging

To exit the debugger you can use the link:https://github.com/derekparker/delve/tree/master/Documentation/cli#exit[`exit`]
command or press kbd:[Ctrl+d], just like you would exit any Bash for example:

----
(dlv) exit
Would you like to kill the process? [Y/n] y
----

You are being asked if you want to kill the process and the answer to this
question very much depends on the way you've started *delve*. If you've attached
to a running process like we did, the answer to this question is probably *no*.
And if you've just started the program under test for debugging purposes then
you might as well answer y to stop it.

Imports 13 package(s)

  1. github.com/almighty/almighty-core/migration
  2. github.com/almighty/almighty-core/transaction
  3. github.com/goadesign/goa/middleware/security/jwt
  4. github.com/jinzhu/gorm
  5. github.com/dgrijalva/jwt-go
  6. github.com/almighty/almighty-core/models
  7. golang.org/x/net/context
  8. github.com/almighty/almighty-core/app
  9. github.com/lib/pq
  10. github.com/almighty/almighty-core/query/simple
  11. github.com/goadesign/goa/middleware
  12. github.com/almighty/almighty-core/remoteworkitem
  13. github.com/goadesign/goa

Test imports 4 package(s)

  1. github.com/stretchr/testify/suite
  2. github.com/almighty/almighty-core/app/test
  3. github.com/stretchr/testify/assert
  4. github.com/almighty/almighty-core/resource