diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff3ca9b..91d43f7 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 diff --git a/README.md b/README.md index f0b0433..efff7bf 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,11 @@ 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 +22,7 @@ industry standards. - **OpenTelemetry** for native observability. - **Springdoc OpenAPI 3** for Swagger documentation. -## Getting Started +## 🛠️ Getting Started ### Prerequisites @@ -28,7 +32,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 +49,54 @@ 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 +Comprehensive endpoint details and data contracts are available at: -- **POST `/authenticate`**: Login and receive a JWT token. -- **GET `/users`**: User management and social graph. -- **GET `/posts`**: Scalable paginated feed access. +- [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.