An hypothetical document to exemplify how a "Source Code Guide" might look like.

SourceCodeGuide.md

Source Code Guide

This is a guide to aims to provide to our developers the directions needed to deal with the source of this service.

Requirements

To run this project you need the following tools and SDKs installed on your Operating System:

• Java Development Kit 13 or superior
• Rust 1.33 or superior
• Docker 18 or superior
• Bash-compatible shell

Source Code Structure

This project structure was split into a few folders to keep it organised and easy to understand. They are:

• infrastructure - where AWS infrastructure definition is placed
• deployment - contains auto-generated scripts to deploy the services
• local-development - contains scripts that spins up PostgreSQL, Redis and mocks of AWS infrastructure for local development
• source - the source code of the service

Importing the project on your IDE

Each of the folders above described can (and should) be imported as an independent project. It was heavily tested using VSCode and Intellij IDEA. The import process should be as trivial as any other project.

Running and Testing Locally

Before run the software, open a terminal and type the command below. It will spin up all the dependencies required to run this service locally.

$ ./local-development/local.sh start

To build, package and run the software locally type the following command:

$ ./source/builder.sh run

If the build was successful it will be listening to the port http://localhost:8801.

Running the tests

To run all automated tests (unit, integration and contract tests) please be sure you have started the local development environment. For more details, look at the topic above.

Open the terminal and type the following command:

$ ./source/builder.sh run-all-tests

You can replace run-all-tests by:

• run-unit-tests to run only Unit Tests
• run-contract-tests to run only Contract Tests
• run-integration-tests to run only Integration Tests

Deploying your software

You probably don't have enough permission to perform this from your machine, but this steps are hereby documented so you can understand what is happening in the CI/CD pipeline.

The deployment script relies on a previously (and successfully) generated package. To generate a package, type the following command:

$ ./source/builder.sh package

To deploy this service you just have to type the following command:

$ ./deployment/deploy.sh staging

The above commadn will deploy the generated package (in this case a Docker image) to staging. You can replace staging with production to deploy it into production.