Skip to content

Commit 485cc18

Browse files
Copilotthomasturrell
Copilot
and
thomasturrell
committed
Create CONTRIBUTING.md and update README.md
Co-authored-by: thomasturrell <1552612+thomasturrell@users.noreply.github.com>
1 parent 7f8aefd commit 485cc18

2 files changed

Lines changed: 346 additions & 21 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
# Contributing to xAPI Java
2+
3+
Thank you for your interest in contributing to xAPI Java! This document provides guidelines and instructions for contributing to this project.
4+
5+
## Table of Contents
6+
7+
- [Code of Conduct](#code-of-conduct)
8+
- [Getting Started](#getting-started)
9+
- [Prerequisites](#prerequisites)
10+
- [Setting Up Your Development Environment](#setting-up-your-development-environment)
11+
- [Development Workflow](#development-workflow)
12+
- [Building the Project](#building-the-project)
13+
- [Running Tests](#running-tests)
14+
- [Code Style and Formatting](#code-style-and-formatting)
15+
- [Making Changes](#making-changes)
16+
- [Creating a Branch](#creating-a-branch)
17+
- [Writing Code](#writing-code)
18+
- [Writing Tests](#writing-tests)
19+
- [Documentation](#documentation)
20+
- [Submitting Changes](#submitting-changes)
21+
- [Pull Request Process](#pull-request-process)
22+
- [Pull Request Checklist](#pull-request-checklist)
23+
- [Code Review Process](#code-review-process)
24+
- [Project Structure](#project-structure)
25+
- [Additional Resources](#additional-resources)
26+
27+
## Code of Conduct
28+
29+
This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to conduct@berrycloud.co.uk.
30+
31+
## Getting Started
32+
33+
### Prerequisites
34+
35+
xAPI Java requires **Java 25 or newer**.
36+
37+
#### Installing Java 25
38+
39+
We recommend using [SDKMAN!](https://sdkman.io/) to install and manage Java versions:
40+
41+
```bash
42+
# Install SDKMAN (if not already installed)
43+
curl -s "https://get.sdkman.io" | bash
44+
45+
# Install Java 25 (Temurin distribution recommended)
46+
sdk install java 25.0.1-tem
47+
48+
# Verify installation
49+
java -version
50+
```
51+
52+
**Note**: The exact identifier (e.g., `25.0.1-tem`) may vary by platform and availability. Run `sdk list java` to see available Java 25 versions for your system and choose the appropriate one for your platform.
53+
54+
### Setting Up Your Development Environment
55+
56+
1. **Fork the repository** on GitHub
57+
58+
2. **Clone your fork** locally:
59+
```bash
60+
git clone https://github.com/YOUR_USERNAME/xapi-java.git
61+
cd xapi-java
62+
```
63+
64+
3. **Add the upstream repository** as a remote:
65+
```bash
66+
git remote add upstream https://github.com/BerryCloud/xapi-java.git
67+
```
68+
69+
4. **Verify your setup**:
70+
```bash
71+
./mvnw clean verify
72+
```
73+
74+
## Development Workflow
75+
76+
### Building the Project
77+
78+
xAPI Java uses Maven with the Maven Wrapper (`./mvnw`). The following build commands are available:
79+
80+
```bash
81+
# Clean build with tests
82+
./mvnw clean verify
83+
84+
# Build without tests (faster, for quick checks)
85+
./mvnw clean verify -DskipTests
86+
87+
# Run tests only
88+
./mvnw test
89+
90+
# Run integration tests
91+
./mvnw verify
92+
```
93+
94+
**Best Practice**: Always run the full build (`./mvnw clean verify`) before starting work to ensure you understand the current state of the project.
95+
96+
### Running Tests
97+
98+
xAPI Java has over 300 unit tests ensuring conformance with the xAPI specification. Tests use:
99+
- **JUnit 5 (Jupiter)** for test framework
100+
- **Hamcrest matchers** for assertions
101+
- **MockWebServer (OkHttp)** for testing HTTP interactions in xapi-client
102+
103+
To run tests:
104+
105+
```bash
106+
# Run all tests
107+
./mvnw test
108+
109+
# Run tests for a specific module
110+
./mvnw test -pl xapi-model
111+
112+
# Run a specific test class
113+
./mvnw test -Dtest=StatementTest
114+
```
115+
116+
### Code Style and Formatting
117+
118+
xAPI Java strictly follows the **[Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)**.
119+
120+
#### Automated Enforcement
121+
122+
- **[CheckStyle](https://checkstyle.sourceforge.io)** is configured to enforce the Google Java Style Guide automatically during the build
123+
- CheckStyle validation runs as part of `./mvnw verify`
124+
- **All CheckStyle violations must be resolved before submitting a pull request**
125+
126+
#### Code Quality Tools
127+
128+
The project uses several automated code quality tools:
129+
130+
- **[SonarCloud](https://sonarcloud.io/summary/new_code?id=BerryCloud_xapi-java)**: Performs automatic pull request reviews and tracks code quality metrics
131+
- **[CodeQL](https://codeql.github.com)**: Scans for security vulnerabilities
132+
- **JaCoCo**: Measures code coverage (viewable in SonarCloud)
133+
134+
These tools run automatically on pull requests via GitHub Actions.
135+
136+
#### Key Style Points
137+
138+
- Use **Lombok** annotations to reduce boilerplate (`@Builder`, `@Value`, `@Getter`, etc.)
139+
- All model classes are **immutable** with **fluent interface** patterns
140+
- Use **Jakarta Bean Validation** annotations for validation (`@NotNull`, custom validators)
141+
- Follow existing code patterns and conventions in the module you're modifying
142+
143+
## Making Changes
144+
145+
### Creating a Branch
146+
147+
Create a feature branch from the latest `main`:
148+
149+
```bash
150+
git checkout main
151+
git pull upstream main
152+
git checkout -b feature/your-feature-name
153+
```
154+
155+
Use descriptive branch names:
156+
- `feature/add-something` for new features
157+
- `fix/issue-number-description` for bug fixes
158+
- `docs/update-readme` for documentation changes
159+
- `chore/update-dependencies` for maintenance tasks
160+
161+
### Writing Code
162+
163+
#### Follow the Fluent Interface Pattern
164+
165+
All xAPI model objects are **immutable** and use a **fluent interface** pattern:
166+
167+
```java
168+
Statement statement = Statement.builder()
169+
.agentActor(a -> a.name("A N Other").mbox("mailto:another@example.com"))
170+
.verb(Verb.ATTEMPTED)
171+
.activityObject(o -> o.id("https://example.com/activity/simplestatement")
172+
.definition(d -> d.addName(Locale.ENGLISH, "Simple Statement")))
173+
.build();
174+
```
175+
176+
To create modified versions of immutable objects, use `toBuilder()`:
177+
178+
```java
179+
Statement completedStatement = attemptedStatement.toBuilder()
180+
.verb(Verb.COMPLETED)
181+
.build();
182+
```
183+
184+
#### Validation
185+
186+
- Use Jakarta Bean Validation annotations for model validation
187+
- Custom validators are in `dev.learning.xapi.model.validation.constraints`
188+
- Ensure validation conforms to the [xAPI specification](https://github.com/adlnet/xAPI-Spec)
189+
190+
#### Jackson Serialization
191+
192+
Custom Jackson modules ensure strict xAPI compliance:
193+
- `XapiStrictLocaleModule`: Validates locale formats
194+
- `XapiStrictNullValuesModule`: Handles null value validation
195+
- `XapiStrictObjectTypeModule`: Validates objectType fields
196+
- `XapiStrictTimestampModule`: Validates timestamp formats
197+
198+
### Writing Tests
199+
200+
**All new functionality must include tests.**
201+
202+
#### Test Structure
203+
204+
```java
205+
@Test
206+
@DisplayName("When Statement Has All Properties Then Serialization Works")
207+
void testStatementSerialization() throws JsonProcessingException {
208+
Statement statement = Statement.builder()
209+
.agentActor(a -> a.name("Test User").mbox("mailto:test@example.com"))
210+
.verb(Verb.COMPLETED)
211+
.activityObject(o -> o.id("https://example.com/activity/1"))
212+
.build();
213+
214+
String json = objectMapper.writeValueAsString(statement);
215+
216+
assertThat(json, hasJsonPath("$.actor.name", is("Test User")));
217+
assertThat(json, hasJsonPath("$.verb.id"));
218+
}
219+
```
220+
221+
#### Test Guidelines
222+
223+
- Use JUnit 5 annotations (`@Test`, `@DisplayName`)
224+
- Use Hamcrest matchers for assertions (`assertThat`, `is`, `notNullValue`)
225+
- Use JSON path matchers for verifying serialization (`hasJsonPath`, `hasNoJsonPath`)
226+
- Ensure tests verify xAPI specification compliance
227+
- Follow existing test patterns in the module
228+
229+
### Documentation
230+
231+
- **JavaDoc**: Document all public APIs with comprehensive JavaDoc comments
232+
- **README**: Update if your changes affect usage examples or getting started instructions
233+
- **Code Comments**: Add comments only when necessary to explain complex logic (match existing style)
234+
- Maintain copyright headers in all source files: `Copyright 2016-2025 Berry Cloud Ltd. All rights reserved.`
235+
236+
## Submitting Changes
237+
238+
### Pull Request Process
239+
240+
1. **Ensure all tests pass locally**:
241+
```bash
242+
./mvnw clean verify
243+
```
244+
245+
2. **Commit your changes** with clear, descriptive commit messages:
246+
```bash
247+
git commit -m "Add feature: brief description of change"
248+
```
249+
250+
3. **Push to your fork**:
251+
```bash
252+
git push origin feature/your-feature-name
253+
```
254+
255+
4. **Create a pull request** on GitHub from your fork to the `main` branch of `BerryCloud/xapi-java`
256+
257+
5. **Fill out the pull request template** completely, including:
258+
- Summary of changes
259+
- Issue number being resolved
260+
- Checklist confirmation
261+
262+
### Pull Request Checklist
263+
264+
Before submitting your pull request, verify:
265+
266+
- [ ] Public methods are documented with JavaDoc
267+
- [ ] Public methods are tested with unit tests
268+
- [ ] New and existing tests pass when run locally (`./mvnw clean verify`)
269+
- [ ] There are no CheckStyle warnings or errors
270+
- [ ] Code follows the Google Java Style Guide
271+
- [ ] Changes maintain backward compatibility (unless discussed with maintainers)
272+
- [ ] Commit messages are clear and descriptive
273+
- [ ] Pull request description references the related issue
274+
275+
**Note**: Pull requests cannot be merged unless all status checks pass (tests, CheckStyle, SonarCloud, CodeQL).
276+
277+
### Code Review Process
278+
279+
1. **Automated Checks**: GitHub Actions will automatically run:
280+
- Build and tests
281+
- CheckStyle validation
282+
- SonarCloud analysis
283+
- CodeQL security scanning
284+
285+
2. **Maintainer Review**: A project maintainer will review your code for:
286+
- Correctness and quality
287+
- Adherence to project conventions
288+
- Test coverage
289+
- Documentation completeness
290+
291+
3. **Feedback and Iteration**:
292+
- Address any requested changes
293+
- Push updates to your branch (the PR will update automatically)
294+
- Discuss any questions or concerns in the PR comments
295+
296+
4. **Approval and Merge**: Once approved and all checks pass, a maintainer will merge your PR
297+
298+
## Project Structure
299+
300+
xAPI Java is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) containing multiple Maven modules:
301+
302+
- **`xapi-model/`**: Core xAPI data models (Statement, Actor, Verb, Activity, etc.)
303+
- All classes are immutable with builder pattern
304+
- Extensive validation annotations
305+
- Custom validators for xAPI-specific rules
306+
307+
- **`xapi-client/`**: Spring WebClient-based reactive client for LRS communication
308+
- Implements Statement, State, Agent Profile, and Activity Profile resources
309+
- Fluent request builders
310+
- Auto-configuration via Spring Boot
311+
312+
- **`xapi-model-spring-boot-starter/`**: Spring Boot autoconfiguration
313+
- Configurable validation rules
314+
- Properties prefix: `xapi.model.`
315+
316+
- **`samples/`**: Example applications demonstrating xAPI client usage
317+
- Useful as reference for common patterns
318+
319+
## Additional Resources
320+
321+
- **[README.md](README.md)**: Project overview and usage examples
322+
- **[RELEASING.md](RELEASING.md)**: Release process information (for maintainers)
323+
- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)**: Community standards and behavior expectations
324+
- **[xAPI Specification](https://github.com/adlnet/xAPI-Spec)**: Official xAPI specification
325+
- **[Issues](https://github.com/BerryCloud/xapi-java/issues)**: Bug reports and feature requests
326+
- **[Pull Requests](https://github.com/BerryCloud/xapi-java/pulls)**: Ongoing contributions
327+
- **[GitHub Actions](https://github.com/BerryCloud/xapi-java/actions)**: CI/CD workflow runs
328+
- **[SonarCloud Dashboard](https://sonarcloud.io/summary/new_code?id=BerryCloud_xapi-java)**: Code quality metrics
329+
- **[Maven Central](https://central.sonatype.com/artifact/dev.learning.xapi/xapi-model)**: Published artifacts
330+
331+
---
332+
333+
**Questions or need help?** Feel free to:
334+
- Open an issue for bugs or feature requests
335+
- Ask questions in pull request comments
336+
- Reach out to the maintainers listed in `pom.xml`
337+
338+
Thank you for contributing to xAPI Java! 🎉

‎README.md‎

Lines changed: 8 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,9 @@ There are two projects in this [Monorepo](https://en.wikipedia.org/wiki/Monorepo
66

77
Both the xAPI Client and xAPI Model use a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface). Objects are [immutable](https://en.wikipedia.org/wiki/Immutable_object).
88

9-
[CheckStyle](https://checkstyle.sourceforge.io) is used to enforce the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). Sonar performs automatic pull request reviews. [CodeQL](https://codeql.github.com) scans for vulnerabilities. The number of bugs, code smells and vulnerabilities in the codebase can be viewed in SonarCloud. The code coverage and code duplication percentages can also be viewed in SonarCloud. Over three-hundred unit tests ensure conformance with the xAPI specification.
10-
119
## Requirements
1210

13-
xAPI Java requires Java 25 or newer.
14-
15-
### Installing Java 25
16-
17-
We recommend using [SDKMAN!](https://sdkman.io/) to install and manage Java versions:
18-
19-
```bash
20-
# Install SDKMAN (if not already installed)
21-
curl -s "https://get.sdkman.io" | bash
22-
23-
# Install Java 25 (Temurin distribution recommended)
24-
sdk install java 25.0.1-tem
25-
26-
# Verify installation
27-
java -version
28-
```
29-
30-
**Note**: The exact identifier (e.g., `25.0.1-tem`) may vary by platform and availability. Run `sdk list java` to see available Java 25 versions for your system and choose the appropriate one for your platform.
11+
xAPI Java requires **Java 25 or newer**. See [CONTRIBUTING.md](CONTRIBUTING.md#prerequisites) for detailed installation instructions.
3112

3213
## xAPI Java Client
3314

@@ -510,4 +491,10 @@ public ResponseEntity<Collection<UUID>> postStatements(
510491

511492
## Contributing
512493

513-
For information about creating releases, see [RELEASING.md](RELEASING.md).
494+
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
495+
- Development environment setup
496+
- Code style guidelines
497+
- Building and testing procedures
498+
- Pull request process
499+
500+
For information about creating releases, see [RELEASING.md](RELEASING.md) (maintainers only).

0 commit comments

Comments
 (0)