From 494f5825bfce061c2baa885be828379ba39d372a Mon Sep 17 00:00:00 2001 From: Simon Fred Lubambo Date: Fri, 13 Feb 2026 22:29:10 +0300 Subject: [PATCH] Add contributing guide, issue templates, and label triage docs --- .github/ISSUE_TEMPLATE/bug_report.yml | 88 ++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 61 ++++++++++++ .github/LABELS.md | 71 ++++++++++++++ CONTRIBUTING.md | 103 +++++++++++++++++++++ README.md | 6 ++ 6 files changed, 337 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/LABELS.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..94975e5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,88 @@ +name: Bug report +description: Report a reproducible defect in this starter kit. +title: "[Bug]: " +labels: + - bug + - needs-triage +body: + - type: markdown + attributes: + value: | + Thanks for reporting this issue. Please provide enough detail to reproduce it quickly. + + - type: checkboxes + id: preflight + attributes: + label: Preflight checklist + options: + - label: I searched existing issues and did not find a duplicate. + required: true + - label: I can reproduce this on the latest `main` branch. + required: true + + - type: textarea + id: summary + attributes: + label: Bug summary + description: What is broken? + placeholder: A short description of the defect. + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: Provide exact, ordered steps. + placeholder: | + 1. Run ... + 2. Call endpoint ... + 3. Observe ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + + - type: checkboxes + id: services + attributes: + label: Affected services + options: + - label: naming-server + - label: api-gateway + - label: user-service + - label: template-service + - label: docker-compose / infrastructure + + - type: textarea + id: logs + attributes: + label: Logs and stack traces + description: Paste relevant logs/errors. Avoid secrets. + render: shell + + - type: textarea + id: environment + attributes: + label: Environment + description: Versions and platform details. + placeholder: | + - OS: + - Java version: + - Maven version: + - Docker version: + - Docker Compose version: + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..b2b64fd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Contribution Guide + url: https://github.com/slubambo/SpringBoot-Microservices-StarterKit/blob/main/CONTRIBUTING.md + about: Read the contribution process, standards, and test expectations. + - name: Report a security vulnerability + url: https://github.com/slubambo/SpringBoot-Microservices-StarterKit/security/advisories/new + about: Please report sensitive security issues privately. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..6cd5ab4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,61 @@ +name: Feature request +description: Suggest an improvement for the starter kit. +title: "[Feature]: " +labels: + - enhancement + - needs-triage +body: + - type: markdown + attributes: + value: | + Thanks for suggesting an improvement. Focus on practical impact for starter-kit users. + + - type: textarea + id: problem + attributes: + label: Problem statement + description: What problem does this solve? + placeholder: The current setup makes it hard to ... + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe your preferred approach. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Any other options you considered. + + - type: checkboxes + id: impact-area + attributes: + label: Impact area + options: + - label: onboarding / documentation + - label: service architecture + - label: security + - label: local developer experience + - label: CI/CD and automation + - label: containerization / deployment + + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: What should be true for this to be complete? + placeholder: | + - [ ] ... + - [ ] ... + + - type: textarea + id: notes + attributes: + label: Additional context + description: Links, examples, references. diff --git a/.github/LABELS.md b/.github/LABELS.md new file mode 100644 index 0000000..d59393c --- /dev/null +++ b/.github/LABELS.md @@ -0,0 +1,71 @@ +# Label Guide + +This guide defines how maintainers should label issues and PRs for consistent triage. + +## Core triage labels + +| Label | Purpose | When to use | +|---|---|---| +| `needs-triage` | New and unreviewed issue | Apply by default on issue creation | +| `in-progress` | Actively being worked on | Apply when work starts | +| `blocked` | Cannot proceed | Waiting on dependency/decision | +| `duplicate` | Already tracked elsewhere | Link the source issue and close | +| `invalid` | Not actionable / out of scope | Missing reproducible details or not relevant | +| `wontfix` | Accepted but intentionally not implemented | Add rationale before closing | + +## Type labels + +| Label | Purpose | +|---|---| +| `bug` | Defect or regression | +| `enhancement` | New or improved capability | +| `documentation` | README/docs/templates updates | +| `ci` | CI/CD workflows or pipeline behavior | +| `security` | Security-related changes | +| `refactor` | Internal code restructuring without behavior change | + +## Priority labels + +| Label | Meaning | +|---|---| +| `priority: P0` | Production blocker / critical breakage | +| `priority: P1` | High impact, should be done soon | +| `priority: P2` | Normal backlog priority | +| `priority: P3` | Nice-to-have | + +## Effort labels + +| Label | Typical effort | +|---|---| +| `size: XS` | < 1 hour | +| `size: S` | ~1-4 hours | +| `size: M` | ~1-2 days | +| `size: L` | Multi-day / multi-PR | + +## Community labels + +| Label | Purpose | +|---|---| +| `good first issue` | Beginner-friendly, well-scoped, low-risk task | +| `help wanted` | Seeking external contribution | + +## `good first issue` criteria + +Apply `good first issue` only when all are true: +- clear problem statement and acceptance criteria exist +- minimal architecture/security risk +- can be completed without deep project context +- estimated size is `XS` or `S` + +## Suggested triage flow + +1. Confirm issue type (`bug`, `enhancement`, `documentation`, etc.). +2. Keep `needs-triage` until scope and priority are set. +3. Add one priority label and one size label. +4. Add `good first issue` and/or `help wanted` when appropriate. +5. Remove `needs-triage` once triage is complete. + +## Default labels used by issue templates + +- Bug report template: `bug`, `needs-triage` +- Feature request template: `enhancement`, `needs-triage` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0ad08a1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,103 @@ +# Contributing Guide + +Thanks for contributing to `SpringBoot-Microservices-StarterKit`. + +This project is designed as a practical starter kit, so contributions should optimize for: +- onboarding speed +- clarity of architecture and docs +- reliable local and CI behavior + +## What to contribute + +Useful contribution areas: +- bug fixes and regression tests +- starter-kit improvements (DX, config, docs, templates) +- security hardening and sane defaults +- CI/CD and release workflow improvements + +## Prerequisites + +- Java 21 +- Maven 3.9+ +- Docker + Docker Compose +- Git + +## Local setup + +1. Fork and clone the repository. +2. Create a branch from `main`. +3. Copy environment config: + +```bash +cp .env.example .env +``` + +4. Start the stack (optional for integration testing): + +```bash +docker compose up -d +``` + +## Development workflow + +1. Keep changes focused and scoped to one concern. +2. Prefer environment-driven configuration over hardcoded values. +3. Add/update tests when behavior changes. +4. Update docs when user-facing behavior changes. + +## Branch naming + +Use descriptive branch names, for example: +- `fix/jwt-validation-edge-case` +- `feat/ci-compose-health-check` +- `docs/improve-onboarding` + +## Test and verification + +Before opening a PR, run: + +```bash +(cd naming-server && mvn -B -ntp verify) +(cd user-service && mvn -B -ntp verify) +(cd template-service && mvn -B -ntp verify) +(cd api-gateway && mvn -B -ntp verify) +``` + +For Compose-related changes, also run: + +```bash +docker compose up -d --build +docker compose ps +docker compose down -v +``` + +## Pull request expectations + +Each PR should include: +- clear summary of what changed and why +- testing notes (commands run + outcomes) +- any migration/config impact + +PR checklist: +- [ ] changes are minimal and focused +- [ ] tests pass locally +- [ ] docs updated if needed +- [ ] no secrets committed (`.env`, tokens, credentials) + +## Commit style + +Use short imperative messages, for example: +- `Add compose smoke test for CI` +- `Fix user-service JDBC auth setting` +- `Document Docker publish tag workflow` + +## Issues and labels + +- Use issue templates for bugs and feature requests. +- Maintainers should triage issues using the label guide in `.github/LABELS.md`. +- Apply `good first issue` only to small, low-risk, well-scoped tasks with clear acceptance criteria. + +## Security reports + +Do not open public issues for sensitive vulnerabilities. +Use private reporting through GitHub Security Advisories (or contact maintainers directly). diff --git a/README.md b/README.md index 9403c71..ccb027e 100644 --- a/README.md +++ b/README.md @@ -186,6 +186,12 @@ Repeat for the other service folders and image tags. - Use strong secrets in `.env` for real deployments. - `spring-cloud-config` is optional and disabled in `docker-compose.yml`. +## Contributing + +- Read `CONTRIBUTING.md` before opening issues or pull requests. +- Use the built-in GitHub issue templates for bugs and feature requests. +- Maintainers should apply labels using `.github/LABELS.md`. + ## Repository Layout ```text