Prepare project for student use

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: Java CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  quality:
+    name: Ant Quality Suite
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+
+      - name: Install Ant
+        run: sudo apt-get update && sudo apt-get install -y ant
+
+      - name: Run quality checks
+        run: ant quality

.gitignore

@@ -21,6 +21,8 @@
 # JAR files everywhere EXCEPT lib/
 *.jar
 !lib/*.jar
+lib/tools/
+tools-cache/
 
 # Ant build output
 build/

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+This repository is intended for classroom use. Keep changes small, readable,
+and easy for students to inspect.
+
+## Before Submitting Work
+
+Run the test suite:
+
+```bash
+ant test
+```
+
+For larger changes, run the full build:
+
+```bash
+ant all
+```
+
+To run every verification tool without rebuilding the Javadoc and JAR:
+
+```bash
+ant quality
+```
+
+## Coding Expectations
+
+- Use clear names that match the simulation domain being modeled.
+- Prefer simple control flow over clever shortcuts.
+- Add or update tests when behavior changes.
+- Keep generated files out of commits. The `build/` and `docs/` directories
+  are created by Ant and should remain untracked.
+
+## Suggested Student Workflow
+
+1. Pull the latest version of the repository.
+2. Run `ant test` before making changes.
+3. Make one focused change.
+4. Run `ant test` again.
+5. Run `ant quality` before submitting larger work.
+6. Commit with a short message that explains the behavior changed.

README.md

@@ -48,11 +48,17 @@ SimulationModeling/
 | `ant test` | Compile and run JUnit 5 tests |
 | `ant javadoc` | Generate API docs in `docs/` |
 | `ant jar` | Package classes into `build/simulation.jar` |
-| `ant all` | Full pipeline: clean → compile → test → javadoc → jar |
+| `ant checkstyle` | Run style checks |
+| `ant pmd` | Run PMD source analysis |
+| `ant spotbugs` | Run SpotBugs bytecode analysis |
+| `ant coverage` | Run tests and generate JaCoCo coverage reports |
+| `ant quality` | Run tests, Checkstyle, PMD, SpotBugs, and JaCoCo |
+| `ant all` | Full pipeline: clean → quality → javadoc → jar |
 | `ant clean` | Remove all generated files |
 | `ant resolve` | Download JUnit 5 JARs to `lib/` (needed only if lib/ is absent) |
+| `ant resolve-tools` | Download quality-tool distributions to `lib/tools/` |
 
-## Quick Start
+## Quick Start for Students
 
 ```bash
 # 1. Clone the repository
@@ -62,14 +68,32 @@ cd SimulationModeling
 # 2. Compile and run tests
 ant test
 
-# 3. Build everything (clean + compile + test + javadoc + jar)
+# 3. Try the small example simulation
+java -cp build/classes simulation.examples.CountdownSimulation
+
+# 4. Run the full quality pipeline
+ant quality
+
+# 5. Build everything (clean + quality + javadoc + jar)
 ant all
 
-# 4. Open the generated API documentation
+# 6. Open the generated API documentation
 open docs/index.html   # macOS
 xdg-open docs/index.html  # Linux
 ```
 
+Expected example output:
+
+```text
+time 0.0: 5
+time 1.0: 4
+time 2.0: 3
+time 3.0: 2
+time 4.0: 1
+```
+
+If `ant test` succeeds, your development environment is ready.
+
 ## Extending the Simulation Framework
 
 Subclass `Simulation` and `Event` to model your problem:
@@ -97,9 +121,28 @@ public class QueueingSimulation extends Simulation {
 }
 ```
 
-## Optional Build Tools
+See `src/main/java/simulation/examples/CountdownSimulation.java` for a
+complete runnable example.
+
+## Suggested First Student Tasks
+
+1. Run `ant test` and confirm all tests pass.
+2. Run `simulation.examples.CountdownSimulation`.
+3. Change the countdown length and rerun the example.
+4. Create a new simulation package for your assigned model.
+5. Add tests for any behavior you add or change.
 
-`build.xml` contains commented-out targets for:
+## Repository Hygiene
+
+- Commit source files, tests, documentation, and build configuration.
+- Do not commit generated `build/` or `docs/` files.
+- Keep dependency JARs in `lib/` unless your instructor gives different
+  course-specific instructions.
+- Run `ant test` before each commit.
+
+## Quality Tools
+
+The project includes enabled Ant targets for:
 
 | Tool | Purpose |
 |------|---------|
@@ -108,8 +151,16 @@ public class QueueingSimulation extends Simulation {
 | **PMD** | Source code analysis |
 | **JaCoCo** | Test coverage reporting |
 
-To enable any of these, download the corresponding JAR(s) to `lib/` and
-uncomment the relevant `<target>` in `build.xml`.
+Run everything with:
+
+```bash
+ant quality
+```
+
+The first run downloads tool distributions into `lib/tools/`. Those files are
+local build support and are ignored by Git. Reports are written under
+`build/reports/`, including JaCoCo HTML coverage at
+`build/reports/coverage/index.html`.
 
 ## Running Tests Independently
 

build.properties

@@ -3,8 +3,7 @@
 # ============================================================
 
 # --- Java compiler settings ---
-java.source.version = 17
-java.target.version = 17
+java.release.version = 17
 
 # --- Directory layout ---
 src.main.dir   = src/main/java
@@ -22,3 +21,21 @@ jar.file       = ${build.dir}/simulation.jar
 # --- Project metadata (used in Javadoc) ---
 project.name    = SimulationModeling
 project.version = 1.0
+
+# --- Optional quality tool versions ---
+checkstyle.version = 10.21.4
+spotbugs.version   = 4.9.7
+pmd.version        = 7.10.0
+jacoco.version     = 0.8.12
+junit.platform.version = 1.10.2
+
+# --- Optional quality tool locations ---
+tools.dir       = ${lib.dir}/tools
+downloads.dir   = ${tools.dir}/downloads
+checkstyle.jar  = ${tools.dir}/checkstyle/checkstyle-${checkstyle.version}-all.jar
+spotbugs.home   = ${tools.dir}/spotbugs/spotbugs-${spotbugs.version}
+pmd.home        = ${tools.dir}/pmd/pmd-bin-${pmd.version}
+jacoco.home     = ${tools.dir}/jacoco
+jacoco.ant.jar  = ${jacoco.home}/lib/jacocoant.jar
+junit.console.jar = ${tools.dir}/junit/junit-platform-console-standalone-${junit.platform.version}.jar
+jacoco.exec.file = ${reports.dir}/jacoco.exec