diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md new file mode 100644 index 0000000..fcbfce4 --- /dev/null +++ b/CONTRIBUTIONS.md @@ -0,0 +1,34 @@ +# Contributions — Assignment 15: Cross-Project Contributions + +## Overview + +This document summarises all cross-project contributions made for Assignment 15. Four pull requests were submitted across three peer repositories, all of which were merged successfully with CI passing. + +--- + +## Contribution Plan + +See [CONTRIBUTION_PLAN.md](CONTRIBUTION_PLAN.md) for the full strategy and selected issues. + +--- + +## Pull Requests Submitted + +| # | Repository | PR Link | Issue | Type | Status | +|---|---|---|---|---|---| +| 1 | ElectoView | https://github.com/MaleselaModiba123/ElectoView/pull/34 | #17 | Bug fix | Merged | +| 2 | campus-lost-and-found | https://github.com/Skiet88/campus-lost-and-found/pull/50 | #26 | Tests | Merged | +| 3 | university-research-collaboration-platform | https://github.com/Ngandana/university-research-collaboration-platform/pull/68 | README feature | Feature request | Merged | +| 4 | university-research-collaboration-platform | https://github.com/Ngandana/university-research-collaboration-platform/pull/69 | #4 | Feature request | Merged | + +--- + +## Merged PRs + +See [MERGED_PRS.md](MERGED_PRS.md) for detailed summaries of each merged contribution. + +--- + +## Reflection + +See [REFLECTION_A15.md](REFLECTION_A15.md) for lessons learned and collaboration challenges. diff --git a/CONTRIBUTION_PLAN.md b/CONTRIBUTION_PLAN.md new file mode 100644 index 0000000..da28c70 --- /dev/null +++ b/CONTRIBUTION_PLAN.md @@ -0,0 +1,39 @@ +# Contribution Plan — Assignment 15 + +## Selected Projects + +| Project | Owner | Language | CONTRIBUTING.md | Selected Issue | +|---|---|---|---|---| +| ElectoView | MaleselaModiba123 | Java / Spring Boot | Yes | Issue #17 — structured API error responses | +| campus-lost-and-found | Skiet88 | JavaScript / Node.js | Yes | Issue #26 — edge-case tests for ItemReportBuilder | +| university-research-collaboration-platform | Ngandana | Python / FastAPI | Yes | README feature — pagination; Issue #4 — document upload | + +## Why These Projects + +All three repositories have a clear `CONTRIBUTING.md`, active issue trackers with `good-first-issue` labels, and passing CI pipelines — making them suitable targets for high-quality contributions. + +## Contribution Strategy + +1. **Read CONTRIBUTING.md first** in each repo to understand coding conventions, branch naming, and PR requirements. +2. **Start with tests and focused fixes** (lower risk, faster CI feedback) before tackling features. +3. **Keep PRs small and single-purpose** — one concern per PR to simplify review. +4. **Comment on issues before coding** to avoid duplicate work. +5. **Fix CI failures immediately** rather than merging broken code. + +## Planned Contributions + +### PR 1 — ElectoView (Java / Spring Boot) +- Issue: #17 — Add structured validation error responses +- Approach: Add `@RestControllerAdvice` GlobalExceptionHandler in `za.ac.cput.controller`; also remove a pre-existing duplicate handler in the test exception package that caused a bean conflict and CI failure. + +### PR 2 — campus-lost-and-found (JavaScript / Jest) +- Issue: #26 — Add edge-case tests for ItemReportBuilder +- Approach: Create `Itemreportbuilder.edge.test.js` with 14 tests covering per-field required validation, empty string handling, and Director reset behaviour. + +### PR 3 — university-research-collaboration-platform (Python / FastAPI) +- Feature: Add `skip`/`limit` pagination to list endpoints +- Approach: Add optional `skip` and `limit` query parameters to `GET /api/users`, `GET /api/projects`, and `GET /api/tasks` with backwards-compatible defaults. + +### PR 4 — university-research-collaboration-platform (Python / FastAPI) +- Issue: #4 — Upload Research Document (US-004) +- Approach: Add `POST /api/documents/upload` endpoint using FastAPI `UploadFile`; validates file type (PDF/DOCX) and size (≤50 MB) using existing domain model constants. diff --git a/MERGED_PRS.md b/MERGED_PRS.md new file mode 100644 index 0000000..fd7251e --- /dev/null +++ b/MERGED_PRS.md @@ -0,0 +1,63 @@ +# Merged Pull Requests — Assignment 15 + +All four pull requests were reviewed, CI-verified, and merged by the repository owners. + +--- + +## PR 1 — ElectoView + +**Repository:** https://github.com/MaleselaModiba123/ElectoView +**Pull Request:** https://github.com/MaleselaModiba123/ElectoView/pull/34 +**Issue:** #17 — Add structured validation error responses +**Branch:** `fix/issue-17-clean` +**Status:** Merged + +### Summary of changes +- Added `GlobalExceptionHandler.java` in `za.ac.cput.controller` annotated with `@RestControllerAdvice`. +- Handles `IllegalArgumentException` (400), `IllegalStateException` (409), and `RuntimeException` (404 or 500) with a structured JSON response containing `timestamp`, `status`, `error`, and `message` fields. +- Removed a duplicate `GlobalExceptionHandler.java` from `za.ac.cput.exception` (test package) that was causing a Spring bean conflict and CI failure. + +--- + +## PR 2 — campus-lost-and-found + +**Repository:** https://github.com/Skiet88/campus-lost-and-found +**Pull Request:** https://github.com/Skiet88/campus-lost-and-found/pull/50 +**Issue:** #26 — Add edge-case tests for ItemReportBuilder +**Branch:** `fix/issue-26-itemreportbuilder-edge-tests` +**Status:** Merged + +### Summary of changes +- Created `tests/creational_patterns_tests/Itemreportbuilder.edge.test.js` with 14 new Jest tests. +- Tests cover: per-field required validation (userId, type, title, description, location, dateLostFound individually), empty string / falsy value handling, Director reset behaviour across consecutive builds, and `buildFullFoundReport` after `buildMinimalLostReport`. + +--- + +## PR 3 — university-research-collaboration-platform (pagination) + +**Repository:** https://github.com/Ngandana/university-research-collaboration-platform +**Pull Request:** https://github.com/Ngandana/university-research-collaboration-platform/pull/68 +**Feature:** Add skip/limit pagination to list endpoints (README feature-request) +**Branch:** `docs/issue-63-reflection` +**Status:** Merged + +### Summary of changes +- Added `skip` (default: 0) and `limit` (default: 100, max: 1000) query parameters to `GET /api/users`, `GET /api/projects`, and `GET /api/tasks`. +- All 249 existing tests pass unchanged — defaults preserve previous behaviour exactly. + +--- + +## PR 4 — university-research-collaboration-platform (document upload) + +**Repository:** https://github.com/Ngandana/university-research-collaboration-platform +**Pull Request:** https://github.com/Ngandana/university-research-collaboration-platform/pull/69 +**Issue:** #4 — Upload Research Document (US-004) +**Branch:** `feat/issue-4-document-upload` +**Status:** Merged + +### Summary of changes +- Added `POST /api/documents/upload` endpoint accepting multipart file upload with `title` and `uploader_id` form fields. +- Validates file extension (PDF or DOCX only) and file size (≤50 MB) using constants from the existing `Document` domain model. +- Wired `InMemoryDocumentRepository` via `RepositoryFactory`. +- Added `python-multipart` to `requirements.txt` and the CI install step to support FastAPI form/file handling. +- Returns 201 with document metadata on success; 400 for invalid type or size; 404 for unknown uploader. diff --git a/REFLECTION_A15.md b/REFLECTION_A15.md new file mode 100644 index 0000000..0609ec1 --- /dev/null +++ b/REFLECTION_A15.md @@ -0,0 +1,31 @@ +# Reflection — Assignment 15: Cross-Project Contributions + +## Overview + +Contributing to three peer repositories taught me that open-source collaboration requires far more than writing correct code. It demands understanding unfamiliar codebases quickly, respecting existing conventions, and communicating clearly through commit messages, PR descriptions, and issue references. + +## What I Learned + +### Reading before writing +Before making any change, I had to understand each project's architecture, testing framework, and coding style. ElectoView used Java with Spring Boot and Maven; campus-lost-and-found used Node.js with Jest; and the university-research-collaboration-platform used Python with FastAPI and pytest. Each required a different mental model before a single line of code could be written. + +### CI is not optional +Every PR had to pass CI before it could be merged. On ElectoView, the initial PR failed because the branch included unrelated files and a duplicate `@RestControllerAdvice` bean that prevented the Spring ApplicationContext from loading. On the university-research-collaboration-platform, the document upload PR failed because `python-multipart` was missing from the CI install step — a dependency the workflow had never needed before. Diagnosing and fixing these failures taught me to always verify the full diff before pushing and to check whether new dependencies are reflected in the CI configuration, not just in `requirements.txt`. + +### Small, focused PRs get merged faster +The campus-lost-and-found PR (14 edge-case Jest tests, one new file) was the smoothest contribution — a single file, a clear purpose, and zero risk of breaking existing behaviour. Larger PRs require more context from reviewers and are more likely to attract revision requests. + +### Feature contributions have higher impact +Adding the document upload endpoint and pagination to the university-research-collaboration-platform required understanding the existing service, repository, and domain layers before extending them. These contributions added real user-facing functionality rather than just fixing existing behaviour, which made them more rewarding to deliver. + +## Challenges + +**Dirty git branches:** On ElectoView, the first PR accidentally included over 100 unrelated files because the feature branch was created from the fork's main rather than from upstream/main. The fix was to create a clean branch directly from upstream/main and cherry-pick only the intended file. + +**Pre-existing CI failures:** Some CI failures were unrelated to my changes — for example, the ElectoView integration tests required a live MySQL database that was never configured in the CI environment. Understanding the difference between a failure I introduced and a pre-existing one required reading the full error logs carefully. + +**Missing dependencies in CI:** The python-multipart issue illustrated that adding a dependency to requirements.txt is not enough if the CI workflow installs packages explicitly via pip install rather than via pip install -r requirements.txt. Both files needed to be updated. + +## Conclusion + +Assignment 15 gave me practical experience with the full open-source contribution workflow: forking, branching, coding, testing, pushing, and responding to CI feedback. The skills developed here — reading unfamiliar codebases, writing focused PRs, and fixing CI failures — are directly transferable to real-world software development. diff --git a/docs/screenshots/PR1-ElectoView.png b/docs/screenshots/PR1-ElectoView.png new file mode 100644 index 0000000..2473c8d Binary files /dev/null and b/docs/screenshots/PR1-ElectoView.png differ diff --git a/docs/screenshots/PR1.png b/docs/screenshots/PR1.png new file mode 100644 index 0000000..96a5fad Binary files /dev/null and b/docs/screenshots/PR1.png differ diff --git a/docs/screenshots/PR2-campus-lost-and-found.png b/docs/screenshots/PR2-campus-lost-and-found.png new file mode 100644 index 0000000..9ec3172 Binary files /dev/null and b/docs/screenshots/PR2-campus-lost-and-found.png differ diff --git a/docs/screenshots/PR2.png b/docs/screenshots/PR2.png new file mode 100644 index 0000000..50fe90c Binary files /dev/null and b/docs/screenshots/PR2.png differ diff --git a/docs/screenshots/PR3-university-research-collaboration-platform.png b/docs/screenshots/PR3-university-research-collaboration-platform.png new file mode 100644 index 0000000..6d2a8e3 Binary files /dev/null and b/docs/screenshots/PR3-university-research-collaboration-platform.png differ diff --git a/docs/screenshots/PR3.png b/docs/screenshots/PR3.png new file mode 100644 index 0000000..cccd16f Binary files /dev/null and b/docs/screenshots/PR3.png differ diff --git a/docs/screenshots/PR4-university-research-collaboration-platform.png b/docs/screenshots/PR4-university-research-collaboration-platform.png new file mode 100644 index 0000000..cb7302f Binary files /dev/null and b/docs/screenshots/PR4-university-research-collaboration-platform.png differ diff --git a/docs/screenshots/PR4.png b/docs/screenshots/PR4.png new file mode 100644 index 0000000..be2b554 Binary files /dev/null and b/docs/screenshots/PR4.png differ