Cloning the Repository

This document outlines the methods for obtaining the gs-rest-service project source code. The primary methods are either generating a project archive from the Spring Initializr service or forking and cloning the repository directly from GitHub. Both approaches provide a complete project structure ready for development and building.

The repository contains two main project states: initial and complete. The initial project is a base to start the tutorial from, while the complete project represents the final state after following the guide. The entire project and its contents are distributed under the Apache License, Version 2.0.

Sources: README.adoc, test/run.sh, LICENSE.txt

Methods for Obtaining the Project Code

There are two documented ways to get the project code onto your local machine.

Sources: README.adoc

Method 1: Using Spring Initializr

The recommended approach for starting from scratch is to use the Spring Initializr web service. This service generates a .zip file containing a ready-to-use project structure based on selected dependencies.

The process flow for using Spring Initializr is as follows:

This diagram illustrates the user journey from accessing the Spring Initializr website to having a local project ready for development.

For this specific project, you can use a pre-initialized link which configures the necessary settings and dependencies automatically.

Sources: README.adoc

Method 2: Fork and Clone from GitHub

Alternatively, developers can fork the project from its GitHub repository and then clone their fork. This method is suitable for those who want to contribute to the project or track its history using Git.

The fork and clone workflow is a standard Git process:

This diagram shows forking the repository on GitHub and then cloning it to a local machine.

All contributions made via this method must adhere to the project's contribution guidelines, which require commits to be signed-off, indicating agreement with the Developer Certificate of Origin.

Sources: README.adoc, CONTRIBUTING.adoc

Repository Structure

Once the project is downloaded or cloned, you will find a specific directory structure. The root contains two primary sub-projects: initial and complete.

This structure is confirmed by the test/run.sh script, which navigates into both initial and complete directories to execute build commands.

The following diagram depicts the high-level directory structure:

This shows the main folders within the repository and key files like pom.xml within the initial and complete project folders.

Sources: test/run.sh, initial/pom.xml, complete/pom.xml

Build Configuration

Both the initial and complete projects are configured to be built with either Maven or Gradle. The necessary wrapper scripts (mvnw, gradlew) are included in the repository. The core dependencies are managed through the pom.xml file for Maven builds.

The key dependencies for the complete project are:

• spring-boot-starter-web: Provides dependencies for building web applications, including RESTful applications, using Spring MVC.
• spring-boot-starter-test: Provides dependencies for testing Spring Boot applications.

The project is configured to use Java version 17.

<!-- complete/pom.xml:19-21 -->
<properties>
    <java.version>17</java.version>
</properties>

<!-- complete/pom.xml:23-32 -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

The configuration is nearly identical for the initial project, setting the foundation for the tutorial.

Sources: complete/pom.xml:19-32, initial/pom.xml:19-32

Summary

To begin working with the gs-rest-service project, a developer can either generate a fresh project from Spring Initializr or clone the repository from GitHub. The repository is structured into initial and complete states, allowing a developer to either follow the tutorial from the beginning or examine the final code. The project is licensed under Apache 2.0 and includes all necessary build configurations for Maven and Gradle.

Sources: README.adoc, LICENSE.txt