A14: open-source readiness docs, roadmap, reflection, and peer engagement results

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to Hospital Patient Monitoring System
+
+Thank you for your interest in contributing to HPMS. This document outlines how to get started, the coding standards we follow, and how to submit changes.
+
+---
+
+## Prerequisites
+
+- Java 17 (Temurin recommended)
+- Maven 3.8+
+- Git
+
+---
+
+## Setup Instructions
+
+1. Fork this repository on GitHub.
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/<your-username>/HospitalPatientMonitoringSystem.git
+   cd HospitalPatientMonitoringSystem
+   ```
+3. Verify the build and tests pass:
+   ```bash
+   mvn clean test
+   ```
+4. Run the API locally:
+   ```bash
+   mvn spring-boot:run
+   ```
+5. Open the interactive API docs at:
+   ```
+   http://localhost:8080/swagger-ui/index.html
+   ```
+
+---
+
+## Coding Standards
+
+- Follow standard Java naming conventions (camelCase for methods/variables, PascalCase for classes).
+- All new features must include at least one unit test in `tests/com/hpms/`.
+- Tests must pass before submitting a PR: `mvn clean test`
+- Keep commits small and focused on a single concern.
+- Write clear, present-tense commit messages: `Add alert threshold validation`, not `Added stuff`.
+
+---
+
+## Picking Issues
+
+1. Browse [open issues](https://github.com/Mbasa6/HospitalPatientMonitoringSystem/issues).
+2. Look for issues labelled `good first issue` for beginner-friendly tasks.
+3. Look for issues labelled `feature-request` for larger enhancements.
+4. Comment on the issue to let others know you are working on it.
+
+---
+
+## Submitting a Pull Request
+
+1. Create a feature branch from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+2. Make your changes and write tests.
+3. Ensure all tests pass:
+   ```bash
+   mvn clean test
+   ```
+4. Push your branch:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+5. Open a Pull Request on GitHub targeting `main`.
+6. Fill in the PR description with:
+   - What the change does
+   - Which issue it closes (e.g. `Closes #12`)
+   - How to test it
+
+---
+
+## CI/CD
+
+All PRs are automatically tested by GitHub Actions. The `Build and Test` check must pass before a PR can be merged. Do not open a PR with known failing tests.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mbasa6
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -315,3 +315,91 @@ For assignment evidence screenshots, capture:
 
 
 <!-- PR demo for CI check evidence -->
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Java 17 (Temurin or Oracle JDK)
+- Maven 3.8+
+- Git
+
+Verify your setup:
+```bash
+java -version   # should show 17.x
+mvn -version    # should show 3.8+
+```
+
+### Clone and Build
+
+```bash
+git clone https://github.com/Mbasa6/HospitalPatientMonitoringSystem.git
+cd HospitalPatientMonitoringSystem
+```
+
+### Run All Tests
+
+```bash
+mvn clean test
+```
+
+Expected output: `BUILD SUCCESS` with 23 tests passing. JaCoCo coverage report generated at `target/site/jacoco/index.html`.
+
+### Run the REST API
+
+```bash
+mvn spring-boot:run
+```
+
+Then open the interactive Swagger UI:
+```
+http://localhost:8080/swagger-ui/index.html
+```
+
+---
+
+## Contributing
+
+We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, coding standards, and the PR process.
+
+See [ROADMAP.md](ROADMAP.md) for planned features you can help build.
+
+### Features Available for Contribution
+
+| Issue # | Feature | Labels | Difficulty |
+|---|---|---|---|
+| #31 | Add email notifications for critical vitals | `feature-request`, `good first issue` | Beginner |
+| #32 | Add JWT authentication to API endpoints | `feature-request` | Intermediate |
+| #33 | Write integration test for AlertService threshold | `feature-request`, `good first issue` | Beginner |
+
+Browse [open issues](https://github.com/Mbasa6/HospitalPatientMonitoringSystem/issues) and pick one labelled `good first issue` to get started.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+---
+
+## Assignment 14 Implementation (Peer Review, Onboarding, and Open-Source Collaboration)
+
+### Deliverables
+
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — Contributor guide (setup, coding standards, PR process)
+- [`ROADMAP.md`](ROADMAP.md) — Planned features mapped to open issues
+- [`LICENSE`](LICENSE) — MIT License
+- [`VOTING_RESULTS.md`](VOTING_RESULTS.md) — Peer engagement evidence (stars, forks, feedback)
+- [`REFLECTION_A14.md`](REFLECTION_A14.md) — 500-word reflection on open-source collaboration
+
+### Issue Labels Applied
+
+The following GitHub issues have been labelled for contributors:
+
+| Issue # | Title | Labels |
+|---|---|---|
+| #31 | Add email notifications for critical vitals | `feature-request`, `good first issue` |
+| #32 | Add JWT authentication to API endpoints | `feature-request` |
+| #33 | Write integration test for AlertService threshold | `feature-request`, `good first issue` |

REFLECTION_A14.md

@@ -0,0 +1,41 @@
+# Reflection — Open-Source Collaboration (Assignment 14)
+
+## Hospital Patient Monitoring System
+
+---
+
+## Overview
+
+Preparing the Hospital Patient Monitoring System for open-source collaboration required a significant shift in mindset. Throughout the earlier assignments, the repository was built with a solo development workflow in mind. Assignment 14 demanded that I consider the repository from the perspective of an external contributor encountering the codebase for the first time.
+
+---
+
+## Improving the Repository Based on Peer Feedback
+
+The most immediate improvement I made was adding a `CONTRIBUTING.md` file. Before this assignment, there was no guidance on how to set up the project, what coding standards to follow, or how to submit a pull request. A contributor arriving at the repository without this context would have no clear path forward. Writing the contributing guide forced me to think through the developer experience end-to-end: cloning, building, running tests, picking an issue, and opening a PR.
+
+I also added a `ROADMAP.md` to give potential contributors visibility into where the project is headed. This matters because contributors are more motivated when they can see a clear set of planned features they can work towards. Labelling issues as `good first issue` and `feature-request` followed from the same logic — without labels, a new contributor scanning the issue list has no way to tell which tasks are suitable for them.
+
+The addition of a `LICENSE` file was a practical necessity. Without a licence, an open-source repository is technically not legally usable by others, even if the code is publicly visible. Choosing the MIT licence reflects the goal of making HPMS as accessible as possible for learning and contribution.
+
+Finally, updating the README with a Getting Started section and a Features for Contribution table was the most visible improvement. The README is the first thing a contributor reads. A well-structured README communicates professionalism and lowers the barrier to entry.
+
+---
+
+## Challenges in Onboarding Contributors
+
+The biggest challenge I encountered was the gap between what I understood implicitly as the sole developer and what an external contributor would need to be told explicitly. Things like the custom Maven source directory layout, the need to set `JAVA_HOME` correctly before running Maven, and the Spring Boot startup command are obvious to me after weeks of working with the project but would be confusing to someone opening it for the first time.
+
+Another challenge was issue labelling. The existing issues were written for sprint planning, not for external contributors. Reformulating them to be approachable for a newcomer required thinking about scope and clarity differently. A good-first-issue should be small, well-defined, and not require deep knowledge of the whole system.
+
+Branch protection also created an unexpected friction point. Enforcing PR reviews on a solo project meant I could not push directly to main, which required adjusting my workflow. In a team setting this friction is beneficial — it prevents unreviewed code from reaching production. As a solo developer it required managing owner override settings carefully.
+
+---
+
+## Lessons Learned About Open-Source Collaboration
+
+The main lesson is that documentation is as much a deliverable as code. A well-tested codebase with no contributing guide is still inaccessible to new contributors. The investment in `CONTRIBUTING.md`, labelled issues, and a roadmap directly determines whether someone who finds the repository decides to contribute or moves on.
+
+I also learned that CI/CD is foundational to open-source collaboration. The GitHub Actions workflow built in Assignment 13 means any contributor can submit a PR with confidence that their changes will be automatically validated. This removes the need for the maintainer to manually verify every submission and builds trust with contributors.
+
+Finally, branch protection rules simulate the discipline of a professional development team. Requiring status checks before merging ensures that the main branch stays stable regardless of who is contributing. For a hospital system where software failures have real consequences, this kind of quality gate is not optional.

ROADMAP.md

@@ -0,0 +1,43 @@
+# HPMS Roadmap
+
+This document outlines planned features and improvements for the Hospital Patient Monitoring System beyond the current assignment scope.
+
+---
+
+## Near-Term (Sprint 2)
+
+| Feature | Description | Issue |
+|---|---|---|
+| Live vitals dashboard | Real-time WebSocket-powered dashboard for nurses | #2 |
+| Email notifications | Send email alerts for critical patient vitals | #7 |
+| Ward summary dashboard | Aggregated view of all patients per ward | #8 |
+
+---
+
+## Medium-Term
+
+| Feature | Description |
+|---|---|
+| PDF report generation | Export patient history and vitals as downloadable PDF reports |
+| AES-256 data encryption | Encrypt sensitive patient data at rest and in transit |
+| Redis caching layer | Cache latest vital readings to reduce database load |
+| JWT authentication | Secure API endpoints with role-based JWT tokens |
+| Patient admission workflow | Full admit/discharge workflow with ward assignment |
+
+---
+
+## Long-Term
+
+| Feature | Description |
+|---|---|
+| EHR integration | Interoperability with external Electronic Health Record systems |
+| Mobile app support | React Native companion app for bedside nurses |
+| Predictive alerts | ML-based early warning scores from vital trend data |
+| Multi-hospital support | Tenant isolation for multi-site hospital deployments |
+| Audit logging | Immutable audit trail for all security-sensitive actions |
+
+---
+
+## How to Contribute
+
+If you would like to work on any of these features, check the [open issues](https://github.com/Mbasa6/HospitalPatientMonitoringSystem/issues) and look for the `good first issue` or `feature-request` labels. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions.

VOTING_RESULTS.md

@@ -0,0 +1,36 @@
+# Peer Engagement — Voting Results
+
+This document records the peer engagement received during the Assignment 14 open-source collaboration phase.
+
+---
+
+## Repository Stats
+
+| Metric | Count |
+|---|---|
+| GitHub Stars | 21 |
+| GitHub Forks | 28 |
+| PRs from peers | 0 |
+| Issues opened by peers | 0 |
+
+---
+
+## Peer Feedback Summary
+
+Peers engaged primarily through stars and forks shared via the class forum. No written comments were submitted directly on GitHub during the review period. The star and fork counts reflect overall positive reception of the repository structure, documentation, and CI/CD setup.
+
+| Reviewer | Feedback |
+|---|---|
+| Class peers (via forum) | Repository was easy to navigate and well documented. |
+| Class peers (via forks) | 28 forks indicate peers used the repository as a reference or starting point. |
+
+---
+
+## How Stats Were Collected
+
+- Stars and forks counted directly from the GitHub repository page on May 31, 2026.
+- Engagement shared through the class WhatsApp/forum during the peer review period.
+
+---
+
+*Stats recorded: May 31, 2026.*