From 45c137da1320b270ffe4b33124bcc797460edd77 Mon Sep 17 00:00:00 2001 From: Subhrodip Mohanta Date: Tue, 7 Apr 2026 06:56:19 +0200 Subject: [PATCH 1/4] docs: heavily reference wiki links in README for better developer onboarding Signed-off-by: Subhrodip Mohanta --- README.md | 72 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 38 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index f0b0433..2813d4e 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,10 @@ A robust, high-performance Twitter clone backend built with the latest industry standards. -## Modern Tech Stack +## 🚀 Modern Tech Stack + +For a detailed breakdown of our architectural choices, visit our +[Technology Selection](https://github.com/scaleracademy/twitter-backend-java/wiki/Technology-Selections) wiki page. - **Java 21** (Microsoft Build of OpenJDK) - **Spring Boot 4.0** (Spring Framework 7.0) @@ -18,7 +21,7 @@ industry standards. - **OpenTelemetry** for native observability. - **Springdoc OpenAPI 3** for Swagger documentation. -## Getting Started +## 🛠️ Getting Started ### Prerequisites @@ -28,7 +31,8 @@ industry standards. ### Quick Start -Choose the setup that fits your workflow: +Choose the setup that fits your workflow. For more details, see our +[Installation Guide](https://github.com/scaleracademy/twitter-backend-java/wiki/Installation). #### Option A: Zero-Installation (Full Stack) @@ -44,52 +48,52 @@ Ideal for coding. Runs DB in Docker, App in your IDE/CLI. 1. `cp .env.example .env` 2. `docker compose -f docker-compose.dev.yml up -d` -3. Run the **"Moo API"** configuration in IntelliJ IDEA, or use: +3. Configure your IDE using our [IDE Instructions](https://github.com/scaleracademy/twitter-backend-java/wiki/IDE-Instructions). +4. Run the **"Moo API"** configuration in IntelliJ IDEA, or use: `./mvnw spring-boot:run -Dspring-boot.run.profiles=dev` -4. API: `http://localhost:8080` (Standard) | DB Admin: `http://localhost:8083` +5. API: `http://localhost:8080` | DB Admin: `http://localhost:8083` + +For advanced configuration, visit [Project Configuration](https://github.com/scaleracademy/twitter-backend-java/wiki/Project-Configuration). -## API Documentation +## 📖 API Documentation Access the Interactive Swagger UI at: 👉 `http://localhost:8082/swagger-ui/index.html` -### Key Endpoints - -- **POST `/authenticate`**: Login and receive a JWT token. -- **GET `/users`**: User management and social graph. -- **GET `/posts`**: Scalable paginated feed access. +Comprehensive endpoint details and data contracts are available at: +- [API Endpoints Overview](https://github.com/scaleracademy/twitter-backend-java/wiki/API-Endpoints) +- [Request and Response Models](https://github.com/scaleracademy/twitter-backend-java/wiki/Request-and-Response-Models) +- [How to Test Endpoints](https://github.com/scaleracademy/twitter-backend-java/wiki/How-to-Test-Endpoints) -## Architecture & Best Practices +## 🏗️ Architecture & Best Practices -- **Scalable Pagination**: All list endpoints use `Pageable` to prevent memory - exhaustion. -- **Distroless Containers**: Docker images are built using Google's - **Distroless** images for minimal attack surface and maximum security. -- **Multi-Arch Support**: Official images are published for both `amd64` and - `arm64` architectures. -- **Zero-Qualified Names**: The codebase strictly uses imports for readability - and cleaner syntax. -- **Null Safety**: Integrated **JSpecify** annotations across the service - layer. +- **Scalable Pagination**: All list endpoints use `Pageable`. See our + [Entity Design](https://github.com/scaleracademy/twitter-backend-java/wiki/Entity-Design). +- **Distroless Containers**: Secure, minimal runtime environment. +- **Multi-Arch Support**: Images optimized for `amd64` and `arm64`. +- **Zero-Qualified Names**: The codebase strictly uses imports. +- **Null Safety**: Integrated **JSpecify** annotations. -## CI/CD Pipeline +## 🤖 CI/CD Pipeline -Our pipeline is optimized for robust speed and reliability: +Our pipeline is optimized for robust speed and reliability. Learn more about +how we maintain quality in [Collaboration](https://github.com/scaleracademy/twitter-backend-java/wiki/Collaboration) +and [Static Analysis](https://github.com/scaleracademy/twitter-backend-java/wiki/Static-Analysis). -- **PR Checker**: Runs cross-platform linting (Spotless) and a Docker smoke - build on every PR. -- **Master CI**: Performs artifact archival, CodeQL security scanning, and - multi-arch image distribution to GHCR and DockerHub. +- **PR Checker**: Cross-platform linting and multi-arch smoke builds. +- **Master CI**: Artifact archival, CodeQL scanning, and official distribution. -## Contributing +## 🤝 Contributing We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) -for details on: +and the following wiki sections: +- [Working with Issues](https://github.com/scaleracademy/twitter-backend-java/wiki/Working-with-issues) +- [Reviewing Pull Requests](https://github.com/scaleracademy/twitter-backend-java/wiki/Reviewing-pull-requests) +- [Recognizing Contributors](https://github.com/scaleracademy/twitter-backend-java/wiki/Recognizing-contributors) -- Coding standards (Spotless, JSpecify, etc.) -- Development environment setup -- Pull request process +For our future vision, check the [Roadmap](https://github.com/scaleracademy/twitter-backend-java/wiki/Roadmap). -## License +## 📜 License This project is licensed under the **GNU Affero General Public License v3.0**. +See [LICENSE](LICENSE) for details. From 830664764bd65f57cd23698dc1c2b494f4448c0e Mon Sep 17 00:00:00 2001 From: Subhrodip Mohanta Date: Tue, 7 Apr 2026 07:00:13 +0200 Subject: [PATCH 2/4] docs: add comprehensive wiki references to README Signed-off-by: Subhrodip Mohanta --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2813d4e..9d94a3d 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ Ideal for coding. Runs DB in Docker, App in your IDE/CLI. 3. Configure your IDE using our [IDE Instructions](https://github.com/scaleracademy/twitter-backend-java/wiki/IDE-Instructions). 4. Run the **"Moo API"** configuration in IntelliJ IDEA, or use: `./mvnw spring-boot:run -Dspring-boot.run.profiles=dev` -5. API: `http://localhost:8080` | DB Admin: `http://localhost:8083` +5. API: `http://localhost:8080` (Standard) | DB Admin: `http://localhost:8083` For advanced configuration, visit [Project Configuration](https://github.com/scaleracademy/twitter-backend-java/wiki/Project-Configuration). From fb5f4b3c12060f49a9871fdc621f724f356ff4c1 Mon Sep 17 00:00:00 2001 From: Subhrodip Mohanta Date: Tue, 7 Apr 2026 07:04:16 +0200 Subject: [PATCH 3/4] docs: mandate DCO and Green CI as prerequisites for PR review Signed-off-by: Subhrodip Mohanta --- CONTRIBUTING.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff3ca9b..f75ca43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -124,16 +124,28 @@ To keep the codebase clean and stable, we enforce the following rules: ## Pull Request Process +### 1. Eligibility for Review (The "Green Gate") + +To respect the time of our maintainers, a Pull Request will **not** be +reviewed until the following conditions are met: + +* **DCO Compliance:** Every commit must be signed-off (`git commit -s`). +* **Green CI:** The `PR Checker` workflow must pass successfully on GitHub. +* **No Conflicts:** The PR must be rebased against the latest `master`. + +If your PR is missing sign-offs, you can fix it using: +`git rebase HEAD~N --signoff` (where N is the number of commits). + +### 2. Implementation Steps + 1. **Update Documentation:** If you add or change an API, ensure the Swagger/OpenAPI metadata is updated. 2. **Self-Review:** Go through your changes and ensure no "TODOs" or debug logs are left behind. -3. **CI Check:** Ensure the `PR Checker` workflow passes on GitHub. - -4. **Reviewers:** Assign at least one maintainer for review. Be responsive to - feedback! +3. **Assign Reviewers:** Assign at least one maintainer for review once the CI + is green. Be responsive to feedback! ## License From 49fcfdf7325c44260d2e05b71a2ef1ffd9cbe73e Mon Sep 17 00:00:00 2001 From: Subhrodip Mohanta Date: Tue, 7 Apr 2026 07:10:41 +0200 Subject: [PATCH 4/4] style: fix formatting violations in README and CONTRIBUTING Signed-off-by: Subhrodip Mohanta --- CONTRIBUTING.md | 6 +++--- README.md | 7 +++++-- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f75ca43..91d43f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -129,9 +129,9 @@ To keep the codebase clean and stable, we enforce the following rules: To respect the time of our maintainers, a Pull Request will **not** be reviewed until the following conditions are met: -* **DCO Compliance:** Every commit must be signed-off (`git commit -s`). -* **Green CI:** The `PR Checker` workflow must pass successfully on GitHub. -* **No Conflicts:** The PR must be rebased against the latest `master`. +- **DCO Compliance:** Every commit must be signed-off (`git commit -s`). +- **Green CI:** The `PR Checker` workflow must pass successfully on GitHub. +- **No Conflicts:** The PR must be rebased against the latest `master`. If your PR is missing sign-offs, you can fix it using: `git rebase HEAD~N --signoff` (where N is the number of commits). diff --git a/README.md b/README.md index 9d94a3d..efff7bf 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,8 @@ industry standards. ## 🚀 Modern Tech Stack For a detailed breakdown of our architectural choices, visit our -[Technology Selection](https://github.com/scaleracademy/twitter-backend-java/wiki/Technology-Selections) wiki page. +[Technology Selection](https://github.com/scaleracademy/twitter-backend-java/wiki/Technology-Selections) +wiki page. - **Java 21** (Microsoft Build of OpenJDK) - **Spring Boot 4.0** (Spring Framework 7.0) @@ -51,7 +52,7 @@ Ideal for coding. Runs DB in Docker, App in your IDE/CLI. 3. Configure your IDE using our [IDE Instructions](https://github.com/scaleracademy/twitter-backend-java/wiki/IDE-Instructions). 4. Run the **"Moo API"** configuration in IntelliJ IDEA, or use: `./mvnw spring-boot:run -Dspring-boot.run.profiles=dev` -5. API: `http://localhost:8080` (Standard) | DB Admin: `http://localhost:8083` +5. API: `http://localhost:8080` | DB Admin: `http://localhost:8083` For advanced configuration, visit [Project Configuration](https://github.com/scaleracademy/twitter-backend-java/wiki/Project-Configuration). @@ -61,6 +62,7 @@ Access the Interactive Swagger UI at: 👉 `http://localhost:8082/swagger-ui/index.html` Comprehensive endpoint details and data contracts are available at: + - [API Endpoints Overview](https://github.com/scaleracademy/twitter-backend-java/wiki/API-Endpoints) - [Request and Response Models](https://github.com/scaleracademy/twitter-backend-java/wiki/Request-and-Response-Models) - [How to Test Endpoints](https://github.com/scaleracademy/twitter-backend-java/wiki/How-to-Test-Endpoints) @@ -87,6 +89,7 @@ and [Static Analysis](https://github.com/scaleracademy/twitter-backend-java/wiki We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) and the following wiki sections: + - [Working with Issues](https://github.com/scaleracademy/twitter-backend-java/wiki/Working-with-issues) - [Reviewing Pull Requests](https://github.com/scaleracademy/twitter-backend-java/wiki/Reviewing-pull-requests) - [Recognizing Contributors](https://github.com/scaleracademy/twitter-backend-java/wiki/Recognizing-contributors)