Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
194 lines (142 loc) · 7.92 KB

CONTRIBUTING.md

File metadata and controls

194 lines (142 loc) · 7.92 KB

Contributing to this Project

Thanks for considering contributing to Homelab-Alpha! Your interest and effort are invaluable to our community's growth and the enhancement of our project. Below are some guidelines to streamline your contribution process:

General Guidelines

Communication

Please Avoid Unnecessary Pings

We kindly ask all contributors to refrain from pinging maintainers unless absolutely necessary. Pings should be reserved for critical issues or urgent matters that require immediate attention.

Why: Limiting pings to urgent matters helps maintainers focus on and prioritize essential tasks more effectively.

Code of Conduct

To ensure a welcoming and inclusive environment for everyone, we adhere to a Code of Conduct. Please read and respect it in all your interactions within this project.

AI Contribution Policy

This project allows the use of AI-assisted development tools (e.g., ChatGPT, Copilot, Claude). However, all contributors are fully responsible for the code they submit.

All AI-generated or AI-assisted contributions must be:

  • Fully understood by the contributor
  • Manually reviewed before submission
  • Properly tested to ensure correctness and stability

Submissions that include unverified code, unclear logic, or invalid/hallucinated implementations may be rejected.

For full details, please refer to our dedicated AI Contribution Policy.

Visual Aids

When reporting issues, asking for help, or proposing features, screenshots and screencasts (short videos) can be incredibly helpful. They provide visual context that text alone might miss, making it much easier for maintainers to understand the problem or proposal.

  • Screenshots: Use screenshots to capture specific UI elements, error messages, or visual states.
  • Screencasts: For issues involving complex steps, animations, or transient behavior, a short screencast can be invaluable. Please ensure screencasts are concise and directly illustrate the point.

Getting Started

Discussions

Before opening a new issue, please check the Discussions section. This is the best place to ask questions, share ideas, or discuss potential problems that aren't clear-cut bugs. Engaging in discussions helps keep the issue tracker focused on actionable tasks and can often provide quicker answers or solutions.

Issues

  • Check Existing Issues: Take a look at our list of all issues to see if someone is already working on the problem or feature you're interested in, or if it has already been addressed. If there's an open issue, consider contributing to it.
  • Creating New Issues: If you're opening a new issue, ensure it's clear and concise. Provide detailed descriptions, including steps to reproduce any problems.
  • Indicate Willingness to Work: When submitting a new issue, let us know if you're willing to work on a solution.

Pull Requests

  • Alignment with Project Goals: Before sending a pull request, ensure your contribution aligns with our project's objectives. For significant changes, discussing them in an issue beforehand is beneficial. Check our open pull requests to see if similar work is already in progress.

Workflow and Versioning

We follow the GitHub flow for our versioning workflow.

When you're working on something:

  1. Fork the repository
  2. Clone your forked repository: git clone https://github.com/your-username/docs.git
  3. Create a new branch for your feature or bugfix
  4. Submit a pull request from your branch to our main branch

Code and Style Guidelines

  • Coding Standards: Keep your code neat and consistent with our coding standards.
  • Style Guide: Make sure your pull requests adhere to our Code Style + Standards Guides.
  • Documentation Guidelines: When you contribute new features or make significant changes to the code, please also update the relevant documentation. This ensures that the project remains easy to understand and use for all contributors and users. Good documentation includes clear explanations, examples, and any necessary configuration details.
  • Testing Guidelines: When submitting code, please ensure it's well-tested. Include unit, integration, or end-to-end tests where appropriate to cover your changes and prevent regressions. If you're adding a new feature, please include tests for its functionality. For bugfixes, consider adding a test that reproduces the bug before your fix, and then passes after the fix. Explain how you've tested your changes in your pull request description. If you've run specific commands to test, include them.

Pull Request Size Guidelines

To streamline the review process and increase the likelihood of your contributions being accepted quickly, we ask you to break down large changes into smaller, logical Pull Requests.

Why Smaller PRs?

  • Faster Reviews: Smaller PRs are easier to grasp and understand, allowing reviewers to provide feedback more quickly.
  • Fewer Errors: Isolating changes into smaller, focused parts reduces the chance of introducing new bugs.
  • Easier Debugging: If issues arise, it's much simpler to pinpoint the cause within a limited set of changes.
  • Smoother Integration: Small, incremental changes can be integrated into the main branch more easily, minimizing conflicts.

How to Break Down a Large PR

  1. Identify Logical Units: Look for parts of your change that can stand independently. Think about a new feature, a bugfix, a refactoring of a specific component, or a documentation update.
  2. Create Separate Branches: For each logical unit, create a new branch.
  3. Submit Incremental PRs: Submit PRs for each individual branch. Ensure each PR has a clear, well-defined goal and focuses on a single change.
  4. Reference Related PRs: If PRs are dependent on each other, reference the earlier PR in the description of the subsequent PR (e.g., "This builds upon #PR-number").

How Can You Help?

Keep Homelab-Alpha Up-to-Date

If you notice updates to your favorite operating systems or tools, feel free to open a pull request to incorporate them into Homelab-Alpha. Your contribution will undergo review and merge once validated.

Enhance Documentation and Knowledge Base

At Homelab-Alpha, we're committed to nurturing an educational environment where everyone can contribute to enhancing our documentation. If you excel in writing technical documentation, consider contributing to documents that aid others in learning and growing.

Share Your Ideas

We're always eager to hear your innovative ideas and suggestions for new feature. Share your thoughts or concepts using the feature request link. Your input helps shape our future endeavors!


Licensing

By contributing, you agree to Creative Commons Attribution–NonCommercial–ShareAlike 4.0 (CC BY-NC-SA 4.0) license. See the LICENSE file for more details.


Enjoy and Have Fun

Thanks for contemplating contributing to Homelab-Alpha. Together, we can elevate and refine our project for the entire community to benefit from. We eagerly anticipate your contributions!