docs: Add Community Standards pages

2026-06-04 10:38:19 +08:00 · 2025-09-02 18:00:38 +08:00
parent 661527a80f
commit 809cd5b268
5 changed files with 396 additions and 1 deletions
@@ -0,0 +1,75 @@
 # Code of Conduct
 (English primary version – a brief Chinese note may follow. 中文提示：本文件英文为主，若理解存在困难可联系维护者。)
 This project adopts the principles of the Contributor Covenant v2.1 (https://www.contributor-covenant.org/version/2/1/code_of_conduct/) with project‑specific clarifications below. By participating you agree to uphold this Code.
 ## Our Pledge
 We strive to provide a harassment‑free, inclusive, friendly, and productive environment for everyone, regardless of age, body, disability, ethnicity, sex characteristics, gender identity or expression, level of experience, education, socio‑economic status, nationality, personal appearance, race, caste, religion (or lack thereof), sexual identity or orientation, or technical choices.
 ## Our Standards
 Examples of behavior that contributes to a positive environment:
 - Showing empathy and respect to all participants
 - Giving and gracefully accepting constructive feedback
 - Focusing on what is best for the project and community
 - Being honest about mistakes and seeking improvement
 - Using welcoming and inclusive language
 Examples of unacceptable behavior include:
 - Harassment, discrimination, or derogatory comments
 - Trolling, insulting or antagonistic remarks, personal or political attacks
 - Public or private harassment or sustained disruption of activities
 - Publishing others’ private information without explicit permission
 - Sexualized language, imagery, or unwelcome advances
 - Any other conduct reasonably deemed inappropriate or unsafe
 ## Scope
 This Code applies within all project spaces (repository code, issues, pull requests, discussions, wiki, CI logs) and in public spaces whenever an individual is representing the project or community.
 ## Responsibilities & Enforcement
 Project maintainers ("maintainers") are responsible for clarifying standards and taking appropriate, fair, and consistent corrective action.
 Maintainers may remove or edit contributions that violate this Code (comments, commits, code, wiki edits, issues, discussions) and may temporarily or permanently ban any contributor for abusive, harassing, or otherwise harmful behavior.
 ## Reporting
 Report violations privately via:
 - Email: carm@carm.cc
 Please include (if possible):
 - Links, timestamps, or message IDs
 - Description of what happened and why it is a concern
 - Screenshots or logs (if relevant)
 - Preferred or suggested resolution
 We aim to acknowledge reports within 72 hours and provide an initial assessment within 7 days. All good‑faith reports will be treated confidentially and only shared with individuals who need the information to resolve the issue.
 ## Enforcement Guidelines
 Maintainers will use these guidelines to determine the impact of an incident and consequences:
 1. Correction
  - Impact: Use of inappropriate language or other unprofessional conduct.
  - Consequence: Private or public warning, request for change.
 2. Warning
  - Impact: A single severe incident or repeated inappropriate behavior.
  - Consequence: Official warning; continued misconduct leads to escalation.
 3. Temporary Suspension
  - Impact: Persistent violations despite previous warnings.
  - Consequence: Temporary participation suspension (issues/PRs/discussions). Conditions for reinstatement communicated.
 4. Permanent Ban
  - Impact: Demonstrated pattern of harassment, hate, or threats; refusal to reform.
  - Consequence: Permanent removal from community spaces.
 ## Conflicts of Interest
 Maintainers will recuse themselves from enforcement decisions where they have a personal conflict. A neutral maintainer or external trusted community member may be asked to assist when appropriate.
 ## Appeals
 If you believe an enforcement action was made in error or was unfair, you may appeal by emailing the same reporting address within 14 days, providing context and justification.
 ## Attribution
 Portions adapted from Contributor Covenant v2.1 and other open source community best practices.
 ## Changes & Versioning
 Substantive changes to this Code will be announced in the repository (Release Notes / CHANGELOG / Discussions). Historical versions will remain accessible via Git history.
 ---
 If unsure whether something is acceptable: choose respect, transparency, and ask a maintainer before acting.
@@ -0,0 +1,210 @@
 # 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:
 ```bash
 mvn -q clean verify
 ```
 Skip tests (NOT recommended for PR validation):
 ```bash
 mvn -q clean install -DskipTests
 ```
 Run a single module:
 ```bash
 mvn -q -pl core -am test
 ```
 Generate JavaDoc (already bound in build):
 ```bash
 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/<short-name>: New feature work. Open draft PR early for feedback.
 - fix/<issue-id>-<slug>: Bug fix referencing an Issue.
 - chore/<topic>: 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:
 ```bash
 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!
@@ -266,3 +266,11 @@ strong support and active contribution to this project!
 This project's source code is licensed under
 the [GNU LESSER GENERAL PUBLIC LICENSE](https://www.gnu.org/licenses/lgpl-3.0.html).
 ## Project Governance & Contribution
 - Code of Conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
 - Contributing Guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
 - Security Policy: [SECURITY.md](./SECURITY.md)
 For questions, improvements, or security concerns, please refer to the respective document above before opening an issue.
@@ -0,0 +1,102 @@
 # Security Policy
 English is the authoritative language of this document.
 ## Supported Versions
 We generally provide security fixes only for the latest released MINOR version (most recent tag on the default branch). Older versions may receive fixes only if the vulnerability is critical and a patch is low risk.
 | Version  | Status                  |
 |----------|-------------------------|
 | Latest   | Security fixes          |
 | < Latest | Not routinely supported |
 If you rely on an older version you are strongly encouraged to upgrade promptly after each release.
 ## Reporting a Vulnerability
 Please DO NOT open a public Issue for suspected security problems.
 Instead, email: carm@carm.cc with:
 - A clear description of the issue and potential impact
 - Steps to reproduce (minimal code / configuration)
 - Affected version(s) and environment (JDK, OS)
 - Any known workarounds
 - Preferred public credit name (optional)
 You will receive an acknowledgement within 72 hours (workdays) confirming receipt.
 ## Assessment & Disclosure Process
 1. Triage & validation (attempt reproduction, scope impact)
 2. Determine severity (CVSS or qualitative: Low / Moderate / High / Critical)
 3. Prepare a private fix / patch + regression tests
 4. Coordinate an embargoed release window (typically ≤14 days after validation for High/Critical)
 5. Release a new version (and possibly backport if warranted)
 6. Publish security advisory (GitHub Security Advisory + Release Notes) including mitigation steps
 We may reject reports that are clearly non‑security bugs (e.g., feature requests, performance tuning) or issues requiring unreasonable preconditions (e.g., attacker already has full local code execution).
 ## Non-Qualifying Issues (Examples)
 - Missing rate limits on non-authenticated, non-state-changing operations
 - Denial-of-service requiring unrealistic resource constraints or already solved via JVM flags
 - Vulnerabilities only exploitable on unsupported / EOL Java versions
 - Social engineering, SPF/DMARC issues beyond this codebase’s control
 ## Coordinated Disclosure
 If you plan to blog or speak publicly about the vulnerability prior to patch availability, please coordinate timing so users can upgrade safely.
 ## Dependency Security
 We periodically review dependency versions for CVEs. You can help by:
 - Submitting PRs that upgrade vulnerable libraries with changelog & compatibility notes
 - Avoiding unnecessary new dependencies
 ## Cryptographic Material
 This project does not bundle custom cryptographic primitives. If you discover misuse of crypto APIs or insecure random number use in security-sensitive areas, treat it as a security report.
 ## Reporting Format Template (Recommended)
 ```
 Subject: [Security Report] <short title>
 Affected Component: (module / class)
 Version(s) Tested: x.y.z (and earlier if known)
 Environment: JDK x, OS
 Summary:
 Describe the vulnerability and impact.
 Reproduction Steps:
 1. ...
 2. ...
 3. ...
 Expected vs Actual:
 Potential Impact:
 Workarounds / Mitigations (if any):
 Credit: (name / handle / anonymous)
 ```
 ## Credit & Acknowledgement
 We will list (with permission) reporters who submit valid, first responsibly disclosed security issues in the release notes / advisory.
 ## GPG / Integrity
 Release artifacts are signed (see project docs). Always verify signatures and checksums when consuming artifacts from Maven Central or GitHub Packages.
 ## Questions
 For general (non-sensitive) questions, open an Issue labeled `question` rather than using the security email.
 Thank you for helping keep the ecosystem safe.