Contributing
Relevant source files
The following files were used as context for generating this wiki page:This document outlines the process and guidelines for contributing to the gs-rest-service project. This project is a simple "Hello, World" RESTful web service built with Spring. Adhering to these guidelines ensures that your contributions can be integrated smoothly.
The primary contribution requirement is legal: all commits must be signed off, agreeing to the Developer Certificate of Origin (DCO). All code contributions are made under the Apache License 2.0.
Legal Requirements
Sources: CONTRIBUTING.adoc, LICENSE.txt, LICENSE.writing.txt
Before submitting code, you must agree to the licensing and sign-off requirements.
Developer Certificate of Origin (DCO)
All commits must include a Signed-off-by trailer in the commit message. This trailer certifies that you have the right to submit the work under the project's license. You can add this automatically by using the -s flag with your git commit command.
git commit -s -m "Your commit message"
This adds a line to your commit message like: Signed-off-by: Your Name <your.email@example.com>.
Sources: CONTRIBUTING.adoc:1-3
The following diagram illustrates the commit sign-off process.
Project Licensing
The project is governed by the licenses detailed below. Any submitted contribution is assumed to be under these terms.
| Asset Type | License | Details | Source |
|---|---|---|---|
| Source Code | Apache License, Version 2.0 | Contributions are submitted under the terms and conditions of this license. | LICENSE.txt:144-149 |
| Written Works | Creative Commons BY-ND 3.0 | Applies to documentation and other non-code written materials. | LICENSE.writing.txt:1-2 |
Under the Apache License 2.0, a "Contribution" is any work of authorship intentionally submitted for inclusion in the project by the copyright owner or an authorized entity.
Sources: LICENSE.txt:58-70
Development Workflow
To contribute, you'll need to set up a local development environment, make your changes, and run the tests to ensure nothing is broken.
Environment Setup
The project requires the following to build and run:
- Java version: 17
- Build Tool: Maven or Gradle
The project dependencies are managed in the pom.xml file for Maven. Key dependencies include:
spring-boot-starter-web: For building web applications, including RESTful applications.spring-boot-starter-test: For testing Spring Boot applications.
Sources: complete/pom.xml:18, complete/pom.xml:20-30, README.adoc:29-35
Building and Testing
The project includes a shell script to automate the build and test process for both Maven and Gradle. This script is the primary way to validate changes before submission.
Sources: test/run.sh
The testing workflow is as follows:
This diagram shows the sequence of build and compilation commands executed by the run.sh script.
The script executes the following commands to ensure both the initial and complete project states build correctly with both build systems.
| Directory | Command | Purpose |
|---|---|---|
initial | ./mvnw clean compile | Compiles the initial project state using Maven. |
initial | ./gradlew compileJava | Compiles the initial project state using Gradle. |
complete | ./mvnw clean package | Packages the complete application into a JAR file using Maven. |
complete | ./gradlew build | Builds and tests the complete application using Gradle. |
Sources: test/run.sh:4, test/run.sh:10, test/run.sh:16, test/run.sh:26
Writing Tests
New features or bug fixes should be accompanied by tests. The project uses JUnit 5 for testing. Tests for the GreetingController can be found in GreetingControllerTests.java.
Here is an example of a test that verifies the customized greeting message:
// complete/src/test/java/com/example/restservice/GreetingControllerTests.java:42-47
@Test
public void paramGreetingShouldReturnTailoredMessage() throws Exception {
this.mockMvc.perform(get("/greeting").param("name", "Spring Community"))
.andDo(print()).andExpect(status().isOk())
.andExpect(jsonPath("$.content").value("Hello, Spring Community!"));
}
This test sends a GET request to /greeting with a name parameter and asserts that the response body contains the expected tailored message.
Sources: complete/src/test/java/com/example/restservice/GreetingControllerTests.java:42-47
Summary
To contribute to gs-rest-service, you must sign all commits to agree to the DCO. All code contributions fall under the Apache 2.0 license. Before submitting, ensure your changes build successfully and all tests pass by running the provided test/run.sh script.