Add CONTRIBUTING guide, issue templates, and label guidance

.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

.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.

.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.

.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`

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).

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