EasyConfiguration/CONTRIBUTING.md

Contributing Guide

English is the primary language. A brief Chinese hint: 若需中文协助可在 Issue 中说明。

Thank you for investing time in contributing! This document describes how to propose changes and how we maintain quality and consistency across the project.

Quick Links

• Code of Conduct: ./CODE_OF_CONDUCT.md
• Security Policy: ./SECURITY.md
• Issues: https://github.com/CarmJos/configured/issues
• Discussions / Q&A: (open an Issue if Discussions are disabled)

Table of Contents

1. Principles
2. Scope of Contributions
3. Getting Started (Environment & Build)
4. Project Structure
5. Branching & Workflow
6. Issue Workflow
7. Pull Request Guidelines
8. Commit Message Convention
9. Coding Standards
10. Testing Guidelines
11. Documentation & JavaDoc
12. Dependency Policy
13. Versioning & Releases
14. Performance Expectations
15. Internationalization / Language
16. FAQ for Contributors
17. Attribution

---

1. Principles

We value: correctness, clarity, minimalism, maintainability, security-by-default, and performance without premature complexity. Every contribution should move at least one of these forward while not regressing the others.

2. Scope of Contributions

Acceptable contributions include (but are not limited to):

• Bug fixes & test coverage improvements
• Performance optimizations with measurable benefit
• New configuration providers (storage backends) with generic value
• Validation or serialization helpers
• Documentation, examples, or tutorials
• Tooling that improves developer productivity or release robustness

Out-of-scope (likely to be declined):

• Vendor lock‑in features narrowly targeting one proprietary platform (unless optional & isolated)
• Large feature branches without prior design discussion
• Unbounded abstraction that increases complexity with unclear user value

3. Getting Started (Environment & Build)

Requirements:

• JDK 8 (minimum). Later JDKs may work but target bytecode is 1.8.
• Maven 3.8+ (Wrapper optional; project assumes standard mvn).

Build all modules:

mvn -q clean verify

Skip tests (NOT recommended for PR validation):

mvn -q clean install -DskipTests

Run a single module:

mvn -q -pl core -am test

Generate JavaDoc (already bound in build):

mvn -q javadoc:javadoc

4. Project Structure (High-level)

• core/ : Fundamental abstractions (Configuration, Value types, factories)
• features/ : Optional, orthogonal enhancements (validators, section, text, etc.)
• providers/ : Concrete persistence / parsing backends (yaml, gson, hocon, sql, mongodb, temp)
• demo/ : Usage demonstrations & sample scenarios

Rules:

• Core must not depend on feature or provider modules.
• Features must not form cycles; prefer depending only on core.
• Providers should keep external dependencies minimal and shaded/isolated only if necessary.

5. Branching & Workflow

• main (or master): Stable; only fast‑forward / squash from reviewed PRs.
• feature/: New feature work. Open draft PR early for feedback.
• fix/-: Bug fix referencing an Issue.
• chore/: Build, infra, docs improvements.

Never force push to main. Force pushes allowed only to your own feature branches.

6. Issue Workflow

1. Search existing issues first to avoid duplication.
2. Provide reproduction steps (minimal code or config) for bugs.
3. Label suggestions as enhancement; performance items as perf.
4. For larger features, open a design issue summarizing: Problem, Motivation, Proposed API, Alternatives.

7. Pull Request Guidelines

Checklist before opening a PR:

• Linked to at least one Issue (unless trivial doc fix)
• Passes mvn verify
• Adds or updates tests covering new behavior / bug
• Includes JavaDoc / README / CHANGELOG fragment if user-facing
• No unrelated refactors or formatting churn
• Minimal diff: avoid reordering imports unless enforced by style

Review expectations:

• Maintainers strive to respond within 5 business days.
• Use constructive, action‑oriented comments.
• Resolve conversations or explain why not.
• Squash commits if they are noisy; retain meaningful logical grouping.

8. Commit Message Convention

Use Conventional Commits (https://www.conventionalcommits.org/) with optional scope:

<type>(<scope>): <short imperative summary>

<body>(optional)

<footer>(breaking changes, issue references)

Types used:

• feat: New feature (user visible)
• fix: Bug fix
• perf: Performance improvement
• refactor: Internal restructuring without behavior change
• docs: Documentation only
• test: Add or fix tests
• build: Build system or dependency changes
• ci: Continuous integration changes
• chore: Maintenance tasks
• style: Formatting (rare; avoid large style‑only changes)

Breaking changes: add ! after type/scope or include BREAKING CHANGE: footer.

9. Coding Standards

• Java: Follow effective Java principles; prefer explicit types over inference for public APIs.
• Nullability: Use JetBrains annotations (@NotNull, @Nullable) where helpful.
• Immutability: Favor immutable value objects; avoid exposing mutable internal state.
• Exceptions: Use specific exception types; no swallowing silently. Validate inputs early.
• Logging: Keep core logging minimal; let consumers decide verbosity. Avoid println.
• APIs: Minimize surface; avoid exposing prematurely general interfaces.
• Annotations: Provide meaningful config path / comments metadata clearly.

Style

• Indentation: 4 spaces.
• Line length guideline: ≤ 140 chars (soft limit).
• Avoid wildcard imports.

10. Testing Guidelines

• Use JUnit (current: JUnit 4). Prefer deterministic, isolated tests.
• Each bug fix must include a regression test failing before the fix.
• Avoid time‑sensitive sleeps; prefer deterministic constructs.
• Keep provider-specific integration tests under provider module.
• Use random data cautiously; if used, log seed for reproduction.

Command:

mvn -q test

11. Documentation & JavaDoc

• Public classes & methods: brief JavaDoc describing contract, thread-safety, nullability.
• Add code examples when clarifying complex usage.
• Update README or module README for new feature flags or environment variables.
• Keep demo module aligned with latest recommended usage.

12. Dependency Policy

• Keep transitive dependency footprint lean.
• No large frameworks for simple utilities.
• Justify each new dependency in PR description (purpose, size, maintenance risk).
• Prefer stable, well-adopted libraries with permissive licenses compatible with LGPL.
• Security-sensitive libs (parsers, DB drivers) should be periodically updated.

13. Versioning & Releases

• Follows Semantic Versioning (MAJOR.MINOR.PATCH).
• Public API additions => MINOR bump.
• Backwards-compatible bug fix => PATCH.
• Backwards-incompatible change => MAJOR (document rationale & migration).
• Release steps (maintainers):
  1. Ensure main is green (CI all passing)
  2. Update CHANGELOG (if present) or Release Notes draft
  3. Bump versions via maven-release-plugin (ensure GPG & staging configured)
  4. Tag + push; verify publication (Central / GitHub Packages)
  5. Publish GitHub Release with highlights + migration notes

14. Performance Expectations

• Avoid unnecessary object churn in hot paths.
• Profile before large rewrites. Provide benchmark or allocation stats if claiming improvement.
• Defer I/O and heavy parsing until needed (lazy loading pattern).

15. Internationalization / Language

• Primary language: English for code, comments, issues, PRs.
• Chinese clarifications acceptable if accompanied by English.

16. FAQ for Contributors

Q: Can I add a new provider? A: Yes—open a design Issue first summarizing data model, external dependencies, and test strategy.

Q: How do I mark experimental APIs? A: Add JavaDoc: @apiNote Experimental: subject to change without notice. and avoid wide promotion.

Q: Why Java 8 target? A: Maximizes compatibility across server & embedded environments.

17. Attribution

Portions inspired by widely adopted open-source guidelines (Kotlin, Spring, Apache projects) and Conventional Commits.

---

Thank you for helping build a robust configuration ecosystem!