This is an automated email from the ASF dual-hosted git repository.
popduke pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/bifromq-sites.git
The following commit(s) were added to refs/heads/master by this push:
new 3d0e955 [Docs] Clarify the contribution guide (#18)
3d0e955 is described below
commit 3d0e955b4d6f618644be05da0bf34b8771fa5ece
Author: Gu Jiawei <[email protected]>
AuthorDate: Mon Jun 30 10:50:30 2025 +0800
[Docs] Clarify the contribution guide (#18)
Co-authored-by: Yonny Hao <[email protected]>
---
.gitignore | 1 +
.vscode/settings.json | 2 -
docs/contribution_guide/_category_.json | 2 +-
docs/contribution_guide/code_contribution.md | 66 +++++++++++++++++++
docs/contribution_guide/code_review.md | 73 ++++++++++++++++++++++
.../documentation_contribution.md | 64 +++++++++++++++++++
docs/contribution_guide/intro.md | 12 +++-
7 files changed, 215 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..7ff1145
--- /dev/null
+++ b/docs/contribution_guide/code_contribution.md
@@ -0,0 +1,66 @@
+---
+sidebar_position: 2
+title: "Code Contribution"
+---
+
+## Contribute Code to Apache BifroMQ (Incubating)
+
+This guide will walk you through the process of proposing, developing, and
submitting code changes to the project.
+
+### 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
diff --git a/docs/contribution_guide/code_review.md
b/docs/contribution_guide/code_review.md
new file mode 100644
index 0000000..1def409
--- /dev/null
+++ b/docs/contribution_guide/code_review.md
@@ -0,0 +1,73 @@
+---
+sidebar_position: 2
+title: "Code Review"
+---
+
+## Review a Pull Request
+
+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.
diff --git a/docs/contribution_guide/documentation_contribution.md
b/docs/contribution_guide/documentation_contribution.md
new file mode 100644
index 0000000..e361924
--- /dev/null
+++ b/docs/contribution_guide/documentation_contribution.md
@@ -0,0 +1,64 @@
+---
+sidebar_position: 2
+title: "Documentation Contribution"
+---
+
+## Contribute to Documentation
+
+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])
diff --git a/docs/contribution_guide/intro.md b/docs/contribution_guide/intro.md
index bf83027..fc6b404 100644
--- a/docs/contribution_guide/intro.md
+++ b/docs/contribution_guide/intro.md
@@ -1,7 +1,15 @@
---
-id: "overview"
+id: "intro"
sidebar_position: 0
title: "Contribution Guide"
---
-Coming Soon...
+## Contributing to Apache BifroMQ (Incubating)
+
+As an Apache Incubator project, BifroMQ adheres to the principles and
processes of the Apache Way: open, transparent, community-driven development.
Whether you're helping improve the broker engine, fixing a documentation typo,
or proposing new ideas, your contribution makes a meaningful impact.
+
+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)
