evergreen/HACKING.adoc

= How to hack on this project

[CAUTION]
====
The project is under active development.

So though we have automated tests to keep things working, do never hesitate to
come to us on our
link:https://gitter.im/jenkins-infra/evergreen[Gitter channel]
if you have any questions.

We welcome people willing to contribute! :fireworks:

====

== Getting started

This repository _heavily_ depends on link:https://docker.io[Docker] and
GNU/Make.  These tools should be installed and be found via your shell's
`$PATH` environment variable.

Much of this project is developed and testing using Linux, users of another
platform may not find everything works "out of the box." Please feel free to
submit pull requests to improve support for other development environments.


The `Makefile` at the project root should help you getting started.

`make check` or the more specific `make container-check` is likely where you
want to start to understand how things work, and be able to modify them and see
the impact.

=== Running the whole stack locally

To develop on a developer box and quite easily set up both the backend services and the Jenkins Evergreen instance, you need to do the following:

[source,shell, title=from the repo root]
cd distribution/
make run
# wait enough for services to be fully started. Should be <30 seconds.
sleep 30
curl --data-raw "{\"commit\":\"container-tests\",\"manifest\":$(cat ../services/ingest.json)}" \
-H 'Authorization: the API calls are coming from inside the house' \
-H 'Content-Type: application/json' \
http://localhost:3030/update

As soon as you post the `json` into that URL, you should see logs showing Evergreen has started to download plugins and so on.

Then open your browser on http://localhost:8080 and you should see your development version for _Jenkins Evergreen_ coming up.

TIP: Expect some delay for the first time, because you will need to many dozens of MB.
However, an `squid` proxy cache is set up while using this `make run`, hence these downloads should be very fast the next times.

=== Code style

We have defined a set of ESLint rules to keep the code style consistent.
To fix most, if not all, of the formatting issues, use `make fix-formatting`.

=== Tests

Automated testing is exceptionally important for the Jenkins Evergreen effort.
Code should not be introduced without some form of automated testing to ensure
that it it works as specified, and continues to do so.

We use link:https://ci.jenkins.io/blue[Jenkins] to execute our continuous
integration and continuous delivery processes, which are defined in the
`Jenkinsfile` in the root of this repository.

==== Client

The `evergreen-client` is written in JavaScript and have tests written primarily in
link:https://mochajs.org/[Mocha], which can be run via `make check`.

==== Container

We use link:https://github.com/kward/shunit2[shUnit2] for tests.

See the `tests/tests.sh` file to see how this works, and if you want to check additional things.

=== Backend

The backend services are written in JavaScript and have tests written primarily
in link:https://facebook.github.io/jest/[Jest], which can be run via `make check`.

=== How to list available plugins updates

[source,bash]
----
(cd services && make propose-updates)
----

This will tell you which plugins can be upgraded in the
`services/essentials.yaml` file under the `status` section.