This is an automated email from the ASF dual-hosted git repository. gujiaweijoe pushed a commit to branch feat-contribution in repository https://gitbox.apache.org/repos/asf/bifromq-sites.git
commit d4172a614b1cc709e6250282d4aca5b97b05f693 Author: Gu Jiawei <[email protected]> AuthorDate: Sun Jun 29 22:22:43 2025 +0800 1. add some contribution guides. --- .gitignore | 1 + .vscode/settings.json | 2 - docs/contribution_guide/_category_.json | 2 +- docs/contribution_guide/code_contribution.md | 75 +++++++++++++++++++ docs/contribution_guide/code_review.md | 87 ++++++++++++++++++++++ .../documentation_contribution.md | 83 +++++++++++++++++++++ docs/contribution_guide/intro.md | 20 ++++- 7 files changed, 265 insertions(+), 5 deletions(-) diff --git a/.gitignore b/.gitignore index be913af..5bb8efc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ npm-debug.log .DS_Store .idea +.vscode .docusaurus/ node_modules/ package-lock.json diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 7a73a41..0000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,2 +0,0 @@ -{ -} \ No newline at end of file diff --git a/docs/contribution_guide/_category_.json b/docs/contribution_guide/_category_.json index de642b8..5d59fcc 100644 --- a/docs/contribution_guide/_category_.json +++ b/docs/contribution_guide/_category_.json @@ -3,6 +3,6 @@ "position": 9, "link": { "type": "doc", - "id": "contribution_guide/overview" + "id": "contribution_guide/intro" } } diff --git a/docs/contribution_guide/code_contribution.md b/docs/contribution_guide/code_contribution.md new file mode 100644 index 0000000..7b2e402 --- /dev/null +++ b/docs/contribution_guide/code_contribution.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 2 +title: "Code Contribution" +--- + +## Contribute Code to Apache BifroMQ (Incubating) + +We appreciate your interest in contributing code to Apache BifroMQ (Incubating)! This guide will walk you through the process of proposing, developing, and submitting code changes to the project. + +Whether you're fixing a bug, implementing a new feature, or improving test coverage, the BifroMQ community is here to support your contribution. + + +### 1. Find or Propose an Issue + +Before writing any code, we recommend the following: + +* **Check for Existing Issues:** Browse open issues in [GitHub Issues](https://github.com/apache/bifromq/issues) to see if someone is already working on the task. +* **Propose a New Issue:** If your idea is new, open an issue describing the problem or feature clearly. Include motivation, background, and potential approaches. + +> 📬 For larger changes, it's a good idea to discuss your proposal on the [[email protected]](mailto:[email protected]) mailing list before starting implementation. + + +### 2. Work on the Code + +Once an issue is assigned to you or you’ve received a green light from the community: + +#### Clone the Repository + +```bash +git clone https://github.com/apache/bifromq.git +cd bifromq +``` + +#### Follow Coding Guidelines + +Please follow BifroMQ’s: + +* Code style conventions (Java) +* Commit message format (`[Component] Description`) + +> ✅ Tip: Include meaningful tests for your changes and ensure existing tests pass. + + +### 3. Submit a Pull Request (PR) + +Once your changes are ready: + +* Push your branch to your fork +* Open a Pull Request against the target branch +* Reference the corresponding issue in the PR description (e.g., “Fixes #123”) +* Include a clear summary of the changes and motivation + + +### 4. Address Review Feedback + +During the review phase: + +* Engage constructively with feedback +* Revise your code as needed +* Rebase your branch to keep the commit history clean + +Once your PR is approved, a committer will merge it. Congratulations! 🎉 + + +### 5. Merge change + +The code will be merged by a committer once the review is finished. + +After your contribution is merged: + +* Consider picking up another issue +* Help review others’ PRs +* Share your experiences and ideas on the mailing list + +Contributions of all sizes help BifroMQ grow. We appreciate your time and energy! \ No newline at end of file diff --git a/docs/contribution_guide/code_review.md b/docs/contribution_guide/code_review.md new file mode 100644 index 0000000..19e5600 --- /dev/null +++ b/docs/contribution_guide/code_review.md @@ -0,0 +1,87 @@ +--- +sidebar_position: 2 +title: "Code Review" +--- + +## Review a Pull Request + +Code reviews are critical to the quality, stability, and long-term maintainability of Apache BifroMQ (Incubating). As a community-driven project, we welcome everyone — not just committers — to participate in reviewing code. Whether you're new or experienced, your feedback helps improve contributions and shares knowledge across the community. + +Here’s how you can effectively review a Pull Request (PR) in BifroMQ: + + +### 1. Understand the Context + +Before diving into the code: + +* **Read the PR description carefully.** Understand what problem the change solves and how. +* **Check the linked issue**, if any. This gives insight into the motivation, discussion history, and design considerations. +* **Scan the commit message(s)** to ensure they follow the project’s format and are descriptive. + + +### 2. Review Checklist + +While reviewing, consider the following: + +#### ✅ Correctness + +* Does the code behave as described? +* Are edge cases handled properly? +* Is it backwards-compatible? + +#### 🧪 Test Coverage + +* Are there new or updated tests that cover the change? +* Do tests pass locally or in CI? + +#### 💻 Code Quality + +* Is the code clear and easy to understand? +* Are any parts overly complex or in need of refactoring? +* Does the code follow BifroMQ’s style and conventions? + +#### 📁 Design & Architecture + +* Does the change align with the existing architecture? +* Could it introduce unnecessary coupling, duplication, or inefficiency? + +#### 📄 Documentation + +* Are code comments helpful and accurate? +* For user-facing changes, is documentation updated where applicable? + + +### 3. Give Constructive Feedback + +Use GitHub’s review tools to: + +* Ask clarifying questions +* Suggest improvements +* Point out potential bugs +* Praise good practices and elegant solutions + +Be respectful and collaborative — we strive to foster a supportive and inclusive community. Assume positive intent and focus on shared learning and improvement. + + +### 4. Approve or Request Changes + +Once you’re done reviewing: + +* If the PR meets the quality bar, approve it. +* If changes are needed, submit a review with comments and select **“Request changes”**. +* If you're not sure, leave comments and mark the review as **“Comment only”** — others can follow up. + + +### 5. Follow Up + +After leaving your review: + +* Stay engaged if the author responds with updates or questions. +* Re-review the PR after updates and adjust your review status if needed. + + +### Tips for New Reviewers + +* Start by reviewing small PRs — even reviewing spelling fixes or test cases helps. +* Learn from how others review — committers’ comments often reflect good patterns. +* Don’t be afraid to ask questions or admit you’re unsure — it’s part of growing in open-source. diff --git a/docs/contribution_guide/documentation_contribution.md b/docs/contribution_guide/documentation_contribution.md new file mode 100644 index 0000000..b7e785c --- /dev/null +++ b/docs/contribution_guide/documentation_contribution.md @@ -0,0 +1,83 @@ +--- +sidebar_position: 2 +title: "Documentation Contribution" +--- + +## Contribute to Documentation + +Great documentation is essential to the success of Apache BifroMQ (Incubating). Whether you're correcting a typo, improving clarity, or adding new tutorials, your contributions help make BifroMQ more accessible and usable for everyone — from first-time users to advanced developers. + +We welcome and encourage all kinds of documentation improvements! + + +### 📄 What You Can Contribute + +Here are some ways you can help improve the documentation: + +* Fix typos, grammar, or formatting issues +* Clarify instructions or explanations +* Update outdated content +* Add new sections (e.g., feature usage, configuration examples, deployment tips) +* Improve the structure or navigation +* Translate content (when relevant) +* Update or improve the project website + +No contribution is too small — even fixing a broken link makes a difference! + + +### 🛠️ How the Documentation is Organized + +BifroMQ’s documentation is hosted in the main [GitHub repository](https://github.com/apache/bifromq-sites) under: + +``` +docs/ +``` + +* `docs/` contains technical guides, usage examples, and system architecture. + + +### 🧑💻 How to Contribute Documentation + +1. **Fork the Repository** + + Fork [bifromq-sites](https://github.com/apache/bifromq-sites) to your own GitHub account. + +2. **Create a Branch** + + ```bash + git checkout -b feat-xyz + ``` + +3. **Edit or Add Content** + + * Use Markdown for most files. + * Follow the existing writing style and structure. + * Preview locally if making website changes (e.g., using `npm install` then running `npm start`). + +4. **Open a Pull Request** + + * Push your branch and open a PR targeting the `master` branch. + * Use a clear title like: `[Docs] Clarify broker configuration options`. + * Explain what you changed and why. + + +### ✍️ Writing Guidelines + +* Use clear, concise language. +* Favor practical examples and command-line snippets. +* Be consistent in tone (neutral and helpful). +* Link to relevant code or external references when useful. + + +### 🔍 Need Help? + +If you're unsure about what or how to contribute: + +* **Check open issues** labeled `documentation` or `good first issue` +* **Ask on the mailing list:** [[email protected]](mailto:[email protected]) +* **Join the conversation on GitHub Discussions** (if enabled) + + +### 🙌 Thank You! + +Documentation is often the first impression someone has of BifroMQ — your improvements help grow and support the community. We appreciate your contributions! \ No newline at end of file diff --git a/docs/contribution_guide/intro.md b/docs/contribution_guide/intro.md index bf83027..536d8f3 100644 --- a/docs/contribution_guide/intro.md +++ b/docs/contribution_guide/intro.md @@ -1,7 +1,23 @@ --- -id: "overview" +id: "intro" sidebar_position: 0 title: "Contribution Guide" --- -Coming Soon... +## Contributing to Apache BifroMQ (Incubating) + +Welcome to the Apache BifroMQ (Incubating) project — an open-source, high-performance, cloud-native MQTT messaging system designed for large-scale and real-time IoT workloads. + +We are excited that you're interested in contributing to BifroMQ! Whether you're a seasoned open-source contributor or new to the Apache Software Foundation (ASF) ecosystem, we warmly welcome all types of contributions — from bug reports, feature suggestions, and code improvements to documentation updates, tests, and discussions. + +As an Apache Incubator project, BifroMQ adheres to the principles and processes of the Apache Way: open, transparent, community-driven development. Our goal is to build both a great piece of technology and a strong, inclusive community around it. + +In this guide, you'll find everything you need to get started contributing to BifroMQ, including: + +* 🧑💻 [Contribute Code](code_contribution.md) +* 🔍 [Help with Code Reviews](code_review.md) +* 📚 [Improve Documentation and Website](documentation_contribution.md) + +Whether you're helping improve the broker engine, fixing a documentation typo, or proposing new ideas, your contribution makes a meaningful impact. + +Let’s build the future of real-time messaging together — the Apache Way.
