From 7f8aefd3cec3c85bb6b6fa7caab0c19ac72249b3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 18 Nov 2025 15:30:19 +0000 Subject: [PATCH 1/2] Initial plan From 485cc1835f68c4861df69943c4d9e7d04206bb38 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 18 Nov 2025 15:39:14 +0000 Subject: [PATCH 2/2] Create CONTRIBUTING.md and update README.md Co-authored-by: thomasturrell <1552612+thomasturrell@users.noreply.github.com> --- CONTRIBUTING.md | 338 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 29 ++--- 2 files changed, 346 insertions(+), 21 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..bd87a768 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,338 @@ +# Contributing to xAPI Java + +Thank you for your interest in contributing to xAPI Java! This document provides guidelines and instructions for contributing to this project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) + - [Prerequisites](#prerequisites) + - [Setting Up Your Development Environment](#setting-up-your-development-environment) +- [Development Workflow](#development-workflow) + - [Building the Project](#building-the-project) + - [Running Tests](#running-tests) + - [Code Style and Formatting](#code-style-and-formatting) +- [Making Changes](#making-changes) + - [Creating a Branch](#creating-a-branch) + - [Writing Code](#writing-code) + - [Writing Tests](#writing-tests) + - [Documentation](#documentation) +- [Submitting Changes](#submitting-changes) + - [Pull Request Process](#pull-request-process) + - [Pull Request Checklist](#pull-request-checklist) + - [Code Review Process](#code-review-process) +- [Project Structure](#project-structure) +- [Additional Resources](#additional-resources) + +## Code of Conduct + +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. + +## Getting Started + +### Prerequisites + +xAPI Java requires **Java 25 or newer**. + +#### Installing Java 25 + +We recommend using [SDKMAN!](https://sdkman.io/) to install and manage Java versions: + +```bash +# Install SDKMAN (if not already installed) +curl -s "https://get.sdkman.io" | bash + +# Install Java 25 (Temurin distribution recommended) +sdk install java 25.0.1-tem + +# Verify installation +java -version +``` + +**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. + +### Setting Up Your Development Environment + +1. **Fork the repository** on GitHub + +2. **Clone your fork** locally: + ```bash + git clone https://github.com/YOUR_USERNAME/xapi-java.git + cd xapi-java + ``` + +3. **Add the upstream repository** as a remote: + ```bash + git remote add upstream https://github.com/BerryCloud/xapi-java.git + ``` + +4. **Verify your setup**: + ```bash + ./mvnw clean verify + ``` + +## Development Workflow + +### Building the Project + +xAPI Java uses Maven with the Maven Wrapper (`./mvnw`). The following build commands are available: + +```bash +# Clean build with tests +./mvnw clean verify + +# Build without tests (faster, for quick checks) +./mvnw clean verify -DskipTests + +# Run tests only +./mvnw test + +# Run integration tests +./mvnw verify +``` + +**Best Practice**: Always run the full build (`./mvnw clean verify`) before starting work to ensure you understand the current state of the project. + +### Running Tests + +xAPI Java has over 300 unit tests ensuring conformance with the xAPI specification. Tests use: +- **JUnit 5 (Jupiter)** for test framework +- **Hamcrest matchers** for assertions +- **MockWebServer (OkHttp)** for testing HTTP interactions in xapi-client + +To run tests: + +```bash +# Run all tests +./mvnw test + +# Run tests for a specific module +./mvnw test -pl xapi-model + +# Run a specific test class +./mvnw test -Dtest=StatementTest +``` + +### Code Style and Formatting + +xAPI Java strictly follows the **[Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)**. + +#### Automated Enforcement + +- **[CheckStyle](https://checkstyle.sourceforge.io)** is configured to enforce the Google Java Style Guide automatically during the build +- CheckStyle validation runs as part of `./mvnw verify` +- **All CheckStyle violations must be resolved before submitting a pull request** + +#### Code Quality Tools + +The project uses several automated code quality tools: + +- **[SonarCloud](https://sonarcloud.io/summary/new_code?id=BerryCloud_xapi-java)**: Performs automatic pull request reviews and tracks code quality metrics +- **[CodeQL](https://codeql.github.com)**: Scans for security vulnerabilities +- **JaCoCo**: Measures code coverage (viewable in SonarCloud) + +These tools run automatically on pull requests via GitHub Actions. + +#### Key Style Points + +- Use **Lombok** annotations to reduce boilerplate (`@Builder`, `@Value`, `@Getter`, etc.) +- All model classes are **immutable** with **fluent interface** patterns +- Use **Jakarta Bean Validation** annotations for validation (`@NotNull`, custom validators) +- Follow existing code patterns and conventions in the module you're modifying + +## Making Changes + +### Creating a Branch + +Create a feature branch from the latest `main`: + +```bash +git checkout main +git pull upstream main +git checkout -b feature/your-feature-name +``` + +Use descriptive branch names: +- `feature/add-something` for new features +- `fix/issue-number-description` for bug fixes +- `docs/update-readme` for documentation changes +- `chore/update-dependencies` for maintenance tasks + +### Writing Code + +#### Follow the Fluent Interface Pattern + +All xAPI model objects are **immutable** and use a **fluent interface** pattern: + +```java +Statement statement = Statement.builder() + .agentActor(a -> a.name("A N Other").mbox("mailto:another@example.com")) + .verb(Verb.ATTEMPTED) + .activityObject(o -> o.id("https://example.com/activity/simplestatement") + .definition(d -> d.addName(Locale.ENGLISH, "Simple Statement"))) + .build(); +``` + +To create modified versions of immutable objects, use `toBuilder()`: + +```java +Statement completedStatement = attemptedStatement.toBuilder() + .verb(Verb.COMPLETED) + .build(); +``` + +#### Validation + +- Use Jakarta Bean Validation annotations for model validation +- Custom validators are in `dev.learning.xapi.model.validation.constraints` +- Ensure validation conforms to the [xAPI specification](https://github.com/adlnet/xAPI-Spec) + +#### Jackson Serialization + +Custom Jackson modules ensure strict xAPI compliance: +- `XapiStrictLocaleModule`: Validates locale formats +- `XapiStrictNullValuesModule`: Handles null value validation +- `XapiStrictObjectTypeModule`: Validates objectType fields +- `XapiStrictTimestampModule`: Validates timestamp formats + +### Writing Tests + +**All new functionality must include tests.** + +#### Test Structure + +```java +@Test +@DisplayName("When Statement Has All Properties Then Serialization Works") +void testStatementSerialization() throws JsonProcessingException { + Statement statement = Statement.builder() + .agentActor(a -> a.name("Test User").mbox("mailto:test@example.com")) + .verb(Verb.COMPLETED) + .activityObject(o -> o.id("https://example.com/activity/1")) + .build(); + + String json = objectMapper.writeValueAsString(statement); + + assertThat(json, hasJsonPath("$.actor.name", is("Test User"))); + assertThat(json, hasJsonPath("$.verb.id")); +} +``` + +#### Test Guidelines + +- Use JUnit 5 annotations (`@Test`, `@DisplayName`) +- Use Hamcrest matchers for assertions (`assertThat`, `is`, `notNullValue`) +- Use JSON path matchers for verifying serialization (`hasJsonPath`, `hasNoJsonPath`) +- Ensure tests verify xAPI specification compliance +- Follow existing test patterns in the module + +### Documentation + +- **JavaDoc**: Document all public APIs with comprehensive JavaDoc comments +- **README**: Update if your changes affect usage examples or getting started instructions +- **Code Comments**: Add comments only when necessary to explain complex logic (match existing style) +- Maintain copyright headers in all source files: `Copyright 2016-2025 Berry Cloud Ltd. All rights reserved.` + +## Submitting Changes + +### Pull Request Process + +1. **Ensure all tests pass locally**: + ```bash + ./mvnw clean verify + ``` + +2. **Commit your changes** with clear, descriptive commit messages: + ```bash + git commit -m "Add feature: brief description of change" + ``` + +3. **Push to your fork**: + ```bash + git push origin feature/your-feature-name + ``` + +4. **Create a pull request** on GitHub from your fork to the `main` branch of `BerryCloud/xapi-java` + +5. **Fill out the pull request template** completely, including: + - Summary of changes + - Issue number being resolved + - Checklist confirmation + +### Pull Request Checklist + +Before submitting your pull request, verify: + +- [ ] Public methods are documented with JavaDoc +- [ ] Public methods are tested with unit tests +- [ ] New and existing tests pass when run locally (`./mvnw clean verify`) +- [ ] There are no CheckStyle warnings or errors +- [ ] Code follows the Google Java Style Guide +- [ ] Changes maintain backward compatibility (unless discussed with maintainers) +- [ ] Commit messages are clear and descriptive +- [ ] Pull request description references the related issue + +**Note**: Pull requests cannot be merged unless all status checks pass (tests, CheckStyle, SonarCloud, CodeQL). + +### Code Review Process + +1. **Automated Checks**: GitHub Actions will automatically run: + - Build and tests + - CheckStyle validation + - SonarCloud analysis + - CodeQL security scanning + +2. **Maintainer Review**: A project maintainer will review your code for: + - Correctness and quality + - Adherence to project conventions + - Test coverage + - Documentation completeness + +3. **Feedback and Iteration**: + - Address any requested changes + - Push updates to your branch (the PR will update automatically) + - Discuss any questions or concerns in the PR comments + +4. **Approval and Merge**: Once approved and all checks pass, a maintainer will merge your PR + +## Project Structure + +xAPI Java is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) containing multiple Maven modules: + +- **`xapi-model/`**: Core xAPI data models (Statement, Actor, Verb, Activity, etc.) + - All classes are immutable with builder pattern + - Extensive validation annotations + - Custom validators for xAPI-specific rules + +- **`xapi-client/`**: Spring WebClient-based reactive client for LRS communication + - Implements Statement, State, Agent Profile, and Activity Profile resources + - Fluent request builders + - Auto-configuration via Spring Boot + +- **`xapi-model-spring-boot-starter/`**: Spring Boot autoconfiguration + - Configurable validation rules + - Properties prefix: `xapi.model.` + +- **`samples/`**: Example applications demonstrating xAPI client usage + - Useful as reference for common patterns + +## Additional Resources + +- **[README.md](README.md)**: Project overview and usage examples +- **[RELEASING.md](RELEASING.md)**: Release process information (for maintainers) +- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)**: Community standards and behavior expectations +- **[xAPI Specification](https://github.com/adlnet/xAPI-Spec)**: Official xAPI specification +- **[Issues](https://github.com/BerryCloud/xapi-java/issues)**: Bug reports and feature requests +- **[Pull Requests](https://github.com/BerryCloud/xapi-java/pulls)**: Ongoing contributions +- **[GitHub Actions](https://github.com/BerryCloud/xapi-java/actions)**: CI/CD workflow runs +- **[SonarCloud Dashboard](https://sonarcloud.io/summary/new_code?id=BerryCloud_xapi-java)**: Code quality metrics +- **[Maven Central](https://central.sonatype.com/artifact/dev.learning.xapi/xapi-model)**: Published artifacts + +--- + +**Questions or need help?** Feel free to: +- Open an issue for bugs or feature requests +- Ask questions in pull request comments +- Reach out to the maintainers listed in `pom.xml` + +Thank you for contributing to xAPI Java! 🎉 diff --git a/README.md b/README.md index 79b9d831..fa1c59bf 100644 --- a/README.md +++ b/README.md @@ -6,28 +6,9 @@ There are two projects in this [Monorepo](https://en.wikipedia.org/wiki/Monorepo 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). -[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. - ## Requirements -xAPI Java requires Java 25 or newer. - -### Installing Java 25 - -We recommend using [SDKMAN!](https://sdkman.io/) to install and manage Java versions: - -```bash -# Install SDKMAN (if not already installed) -curl -s "https://get.sdkman.io" | bash - -# Install Java 25 (Temurin distribution recommended) -sdk install java 25.0.1-tem - -# Verify installation -java -version -``` - -**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. +xAPI Java requires **Java 25 or newer**. See [CONTRIBUTING.md](CONTRIBUTING.md#prerequisites) for detailed installation instructions. ## xAPI Java Client @@ -510,4 +491,10 @@ public ResponseEntity> postStatements( ## Contributing -For information about creating releases, see [RELEASING.md](RELEASING.md). +We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for: +- Development environment setup +- Code style guidelines +- Building and testing procedures +- Pull request process + +For information about creating releases, see [RELEASING.md](RELEASING.md) (maintainers only).