From 809cd5b26870d6ecdc078b7786573bf6163140cb Mon Sep 17 00:00:00 2001 From: carm Date: Tue, 2 Sep 2025 18:00:38 +0800 Subject: [PATCH] docs: Add Community Standards pages --- .wiki | 2 +- CODE_OF_CONDUCT.md | 75 ++++++++++++++++ CONTRIBUTING.md | 210 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 8 ++ SECURITY.md | 102 ++++++++++++++++++++++ 5 files changed, 396 insertions(+), 1 deletion(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.wiki b/.wiki index c205348..66ace40 160000 --- a/.wiki +++ b/.wiki @@ -1 +1 @@ -Subproject commit c20534860cee3cab46b40cf952b6303488b6f54d +Subproject commit 66ace40bbc1cba3d5e4069487888469f89478190 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..0b9a871 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..eb01008 --- /dev/null +++ b/CONTRIBUTING.md @@ -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/: 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: +``` +(): + +(optional) + +