From bb75532ed059a194a2f404c2be07da2b78b5f90b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 23 Sep 2025 09:24:19 +0000 Subject: [PATCH 1/3] Initial plan From 54c34aff5efdb4243356cc942dd155760b74aaec Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 23 Sep 2025 09:31:43 +0000 Subject: [PATCH 2/3] Add comprehensive Copilot instructions for Scratch for Java repository Co-authored-by: mikebarkmin <2592379+mikebarkmin@users.noreply.github.com> --- .github/copilot-instructions.md | 242 ++++++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..9f4336c7 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,242 @@ +# Copilot Instructions for Scratch for Java + +## Repository Overview + +**Scratch for Java** is a Java library that replicates the functionality and concepts of Scratch, helping learners transition from block-based programming to text-based coding in Java. The library provides an approachable API inspired by Scratch blocks, making it easier for beginners to understand programming concepts while gaining experience with real Java syntax and tools. + +- **Main Package**: `org.openpatch.scratch` +- **Current Version**: 4.24.1 +- **Java Version**: 17 +- **Build Tool**: Maven +- **Documentation Site**: https://scratch4j.openpatch.org +- **Repository Size**: ~5,500 lines of core Java code, 146 reference examples, 59 demo projects + +## High-Level Architecture + +The library is structured around three core concepts: +1. **Window**: The main application window (extends `Window` class) +2. **Stage**: The game/application stage where sprites and elements are displayed +3. **Sprite**: Interactive objects that can move, detect collisions, play sounds, etc. + +### Key Dependencies +- **Processing 4.4.6**: Core graphics and windowing framework +- **Jackson 2.19.2**: JSON/XML processing +- **JOGL 2.5.0**: OpenGL bindings (from jogamp repository) +- **Gluegen 2.5.0**: Native library loading + +## Build Instructions and Known Issues + +### Prerequisites +- Java 17+ (verified with OpenJDK 17.0.16) +- Maven 3.9.11+ +- Node.js + npm (for documentation) + +### Maven Build Commands + +⚠️ **CRITICAL DEPENDENCY ISSUE**: The build currently fails due to network connectivity issues with the jogamp repository (jogamp.org). This is a known external issue. + +**Standard Build Attempts (Currently Failing)**: +```bash +mvn clean compile # FAILS - jogamp dependency issue +mvn clean package # FAILS - jogamp dependency issue +``` + +**Working Build Profiles**: +```bash +# For Maven Central release (includes native dependencies) +mvn clean compile -Pcentral # May work in some environments + +# For standalone JAR with all dependencies +mvn clean package -Pall # Creates target/*-all.jar +``` + +### Build Workarounds +When jogamp repository is unavailable, the build will fail. This is a known issue and not related to code changes. The library uses JOGL for OpenGL graphics rendering. + +### Documentation Build + +The documentation uses **Hyperbook** (Node.js-based static site generator): + +```bash +cd docs +npx hyperbook dev # Start development server +npx hyperbook build # Build static documentation +``` + +Documentation includes: +- English and German versions (`docs/en/` and `docs/de/`) +- Reference examples with generated GIFs +- API documentation generated from Java source + +### Documentation Coverage Validation + +Use the `s4j` script to check documentation coverage: + +```bash +./s4j # Check documentation coverage +./s4j --create # Create missing documentation files +``` + +This script validates that all public classes and methods have corresponding documentation files in both English and German. + +## Project Layout and Architecture + +### Source Code Structure +``` +src/ +├── main/java/org/openpatch/scratch/ +│ ├── Stage.java # Core stage class (1,907 lines) +│ ├── Sprite.java # Core sprite class (2,173 lines) +│ ├── Window.java # Main window class (304 lines) +│ ├── extensions/ # Extension modules +│ │ ├── animation/ # Sprite animation support +│ │ ├── camera/ # Camera/viewport functionality +│ │ ├── color/ # Color manipulation +│ │ ├── fs/ # File system operations +│ │ ├── math/ # Mathematical utilities +│ │ ├── pen/ # Drawing/pen functionality +│ │ ├── recorder/ # GIF/video recording +│ │ ├── shader/ # OpenGL shader support +│ │ ├── shape/ # Geometric shapes +│ │ ├── text/ # Text rendering +│ │ └── timer/ # Timer functionality +│ └── internal/ # Internal implementation classes +└── examples/java/ + ├── demos/ # 59 complete demo projects + └── reference/ # 146 method reference examples +``` + +### Configuration Files +- `pom.xml` - Maven build configuration with multiple profiles +- `.vscode/settings.json` - VS Code Java project settings +- `.vscode/extensions.json` - Recommended VS Code extensions +- `docs/hyperlibrary.json` - Multi-language documentation config +- `.github/workflows/` - CI/CD pipelines + +### Key Build Profiles +- **Default**: Basic compilation (currently broken due to jogamp issue) +- **central**: Maven Central publishing with native dependencies and GPG signing +- **all**: Creates standalone JAR with all dependencies using maven-shade-plugin + +## Continuous Integration and Validation + +### GitHub Workflows + +1. **Version Bump Workflow** (`.github/workflows/version.yml`) + - Triggers on changeset files in `.changeset/` + - Automatically bumps version (patch/minor/major) + - Creates release PR + +2. **Release Workflow** (`.github/workflows/release.yml`) + - Triggers when release PR is merged + - Publishes to Maven Central with GPG signing + - Creates GitHub release with fat JAR + - Publishes Javadocs to GitHub Pages + - Deletes changeset branch + +3. **Javadocs Workflow** (`.github/workflows/javadocs.yml`) + - Builds and publishes API documentation + +### Validation Steps +1. **Documentation Coverage**: Run `./s4j` to ensure all public APIs are documented +2. **Example Compilation**: All reference examples should compile successfully +3. **Maven Build**: Should pass when jogamp repository is accessible +4. **Documentation Build**: `npx hyperbook build` should complete successfully + +## Templates and Starter Projects + +### VS Code Starter Template (`templates/vscode-starter/`) +```java +// MyWindow.java - Main application entry point +import org.openpatch.scratch.Window; + +public class MyWindow extends Window { + public MyWindow() { + super(800, 600, "assets"); + this.setStage(new MyStage()); + } + + public static void main(String[] args) { + new MyWindow(); + } +} +``` + +### BlueJ Starter Template (`templates/bluej-starter/`) +Similar structure optimized for BlueJ IDE. + +## Common Development Patterns + +### Basic Sprite Implementation +```java +import org.openpatch.scratch.Sprite; + +public class MySprite extends Sprite { + public MySprite() { + this.setCostume("name", "path/to/image.png"); + this.setPosition(100, 100); + } + + public void run() { + // Called every frame + this.ifOnEdgeBounce(); + this.move(5); + } +} +``` + +### Stage with Event Handlers +```java +import org.openpatch.scratch.Stage; + +public class MyStage extends Stage { + public MyStage() { + this.add(new MySprite()); + this.setWhenKeyPressed((stage, keyCode) -> { + // Handle key press events + }); + } +} +``` + +## Development Environment Setup + +### VS Code Setup +The repository includes VS Code configuration with: +- Java extension pack recommended +- Hyperbook Studio for documentation editing +- Custom Java source paths including examples +- Java formatter configuration + +### Required Extensions +- `redhat.java` - Java language support +- `openpatch.hyperbook-studio` - Documentation editing + +## Troubleshooting Common Issues + +### Build Failures +1. **jogamp.org dependency errors**: External repository issue, not code-related +2. **Java version mismatch**: Ensure Java 17+ is installed and active +3. **Maven cache issues**: Run `mvn clean` and retry + +### Documentation Issues +1. **Missing documentation warnings**: Run `./s4j --create` to generate templates +2. **Hyperbook build failures**: Ensure Node.js dependencies are installed in `docs/en/` + +### Example Compilation +Examples in `src/examples/java/` should compile with the main source. They're included via the build-helper-maven-plugin. + +## Working with This Repository + +**ALWAYS** trust these instructions and refer to them before exploring. The build system has known external dependencies that may fail intermittently. Focus on: + +1. Understanding the core Sprite/Stage/Window architecture +2. Using the reference examples in `src/examples/java/reference/` as patterns +3. Running `./s4j` to validate documentation coverage +4. Testing documentation builds with `npx hyperbook dev` in the `docs/` directory + +When making changes, ensure: +- All public APIs have corresponding documentation +- Examples compile successfully (when dependencies are available) +- Changes follow the established patterns in existing code +- Documentation is updated in both English and German if adding new features \ No newline at end of file From 135ccfaca3c4c05215d20031861f29a287a4e1e0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 23 Sep 2025 09:46:55 +0000 Subject: [PATCH 3/3] Update Copilot instructions - build now works with jogamp.org allowed Co-authored-by: mikebarkmin <2592379+mikebarkmin@users.noreply.github.com> --- .github/copilot-instructions.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 9f4336c7..abf142c5 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -33,25 +33,23 @@ The library is structured around three core concepts: ### Maven Build Commands -⚠️ **CRITICAL DEPENDENCY ISSUE**: The build currently fails due to network connectivity issues with the jogamp repository (jogamp.org). This is a known external issue. - -**Standard Build Attempts (Currently Failing)**: +**Standard Build Commands**: ```bash -mvn clean compile # FAILS - jogamp dependency issue -mvn clean package # FAILS - jogamp dependency issue +mvn clean compile # Basic compilation +mvn clean package # Create standard JAR +mvn clean test # Run tests (if any) ``` -**Working Build Profiles**: +**Build Profiles**: ```bash # For Maven Central release (includes native dependencies) -mvn clean compile -Pcentral # May work in some environments +mvn clean compile -Pcentral # For standalone JAR with all dependencies mvn clean package -Pall # Creates target/*-all.jar ``` -### Build Workarounds -When jogamp repository is unavailable, the build will fail. This is a known issue and not related to code changes. The library uses JOGL for OpenGL graphics rendering. +**Note**: The library uses JOGL for OpenGL graphics rendering, which requires access to the jogamp.org repository. This dependency is now working correctly in the CI environment. ### Documentation Build @@ -140,7 +138,7 @@ src/ ### Validation Steps 1. **Documentation Coverage**: Run `./s4j` to ensure all public APIs are documented 2. **Example Compilation**: All reference examples should compile successfully -3. **Maven Build**: Should pass when jogamp repository is accessible +3. **Maven Build**: Standard build commands work with all profiles 4. **Documentation Build**: `npx hyperbook build` should complete successfully ## Templates and Starter Projects @@ -215,9 +213,9 @@ The repository includes VS Code configuration with: ## Troubleshooting Common Issues ### Build Failures -1. **jogamp.org dependency errors**: External repository issue, not code-related +1. **Maven cache issues**: Run `mvn clean` and retry 2. **Java version mismatch**: Ensure Java 17+ is installed and active -3. **Maven cache issues**: Run `mvn clean` and retry +3. **Dependency download issues**: Check network connectivity and retry ### Documentation Issues 1. **Missing documentation warnings**: Run `./s4j --create` to generate templates @@ -228,7 +226,7 @@ Examples in `src/examples/java/` should compile with the main source. They're in ## Working with This Repository -**ALWAYS** trust these instructions and refer to them before exploring. The build system has known external dependencies that may fail intermittently. Focus on: +**ALWAYS** trust these instructions and refer to them before exploring. Focus on: 1. Understanding the core Sprite/Stage/Window architecture 2. Using the reference examples in `src/examples/java/reference/` as patterns @@ -237,6 +235,6 @@ Examples in `src/examples/java/` should compile with the main source. They're in When making changes, ensure: - All public APIs have corresponding documentation -- Examples compile successfully (when dependencies are available) +- Examples compile successfully - Changes follow the established patterns in existing code - Documentation is updated in both English and German if adding new features \ No newline at end of file