Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
127 lines (90 loc) · 6.42 KB

CONTRIBUTING.md

File metadata and controls

127 lines (90 loc) · 6.42 KB
Raw

Contributing to CinderPeak

Welcome to CinderPeak, a graph library designed to simplify graph representation and manipulation. We greatly appreciate your interest in contributing! Whether you're fixing bugs, adding features, or enhancing documentation, your contributions help make CinderPeak better.

Open-Source Participation

CinderPeak is an independent, community-driven project that occasionally takes part in recognized open-source programs. This year, we are taking part in NSOC'26 (Nexus Spring of Code).

Contributions are welcome from everyone, whether you are participating through an open-source program or contributing independently. All contributors are expected to follow the project's contribution guidelines, code of conduct, and established best practices to ensure a respectful and productive collaboration.

Important Note

CinderPeak is a complex and critical graph library with significant impact. We welcome contributions from those fully dedicated to delivering high-quality work and who understand the project's importance.

  • Know Your Changes: Fully understand your code or proposed changes, their purpose, and how they affect the system.
  • Explain Clearly: Include clear and detailed explanations, covering why you made specific choices and what the changes do.
  • Be Ready for Review: Code reviews are thorough. You must explain every decision clearly, or your changes will not be accepted.
  • No Low-Quality Work: Code that is untested, rushed, or generated by AI without careful review will be rejected.
  • Write with Care: Every line of code must be precise and show respect for the project's complexity.

If you contribute, you must know your work completely. This is the minimum standard for all contributions to CinderPeak.

How to Contribute

  1. Create an Issue: If you have a suggestion for an enhancement, a new feature, or a bug fix, open an issue in the repository's issues section: CinderPeak Issues.
  2. Wait for Issue Assignment: Only work on issues assigned to you. See the Issue Management section for details.
  3. Fork the Repository: Fork the CinderPeak repository on GitHub.
  4. Clone Your Fork: 
    git clone https://github.com/your-username/CinderPeak.git
  5. Create a Branch: Create a branch for your feature or bug fix: 
    git checkout -b feature/your-feature-name
  6. Write Code and Tests: Ensure your code adheres to the Coding Guidelines and includes appropriate tests.
  7. Submit a Pull Request (PR): Submit a PR with a clear description of your changes, including the issue number it addresses.

Issue Management

Assignment Process

  • First-Come, First-Served: Issues are assigned to the first person who comments requesting assignment.
  • Work Only on Assigned Issues: You may only work on issues assigned to you. PRs for unassigned issues will not be accepted or merged.
  • One Issue at a Time: To request a new issue assignment, your current assigned issue's PR must be at least approved (merged or not).

Activity Requirements

  • Stay Active: Maintain regular progress on your assigned issues.
  • 3-Day Inactivity Rule: Issues inactive for 3 days after assignment will be marked as stale.
  • Reassignment: After being marked stale, you have an additional 12 hours to resume work. After this grace period, the issue will be reassigned to another contributor.

Need More Time?

If you need an extension, notify the maintainer before your issue is marked stale to avoid reassignment. We understand that life happens and are happy to accommodate reasonable requests.

Pull Request Management

Before Submitting

  • Stay in Sync: Ensure your PR is up-to-date with the latest changes from the main branch. Regularly run git pull and rebase to incorporate upstream changes.
  • Test Your Changes: Verify that all tests pass and your code compiles without warnings.

PR Requirements

Your pull request must include:

  • A clear description of your changes
  • The issue number it addresses
  • Adherence to project coding standards
  • Necessary documentation updates
  • Test cases for new features or bug fixes
  • Meaningful commit messages

Activity Requirements

  • Stay Active: Respond to review comments and make requested changes promptly.
  • 3-Day Inactivity Rule: PRs inactive for 3 days will be marked as stale.
  • Closure: After being marked stale, you have an additional 12 hours to resume activity. After this grace period, the PR will be closed and the corresponding issue will be unassigned.

Additional Guidelines

Communication

  • Ask Questions: Use GitHub Discussions or Discord to seek clarification or discuss ideas.
  • Discuss Major Changes: For significant features or architectural changes, discuss your approach with maintainers before starting work to ensure alignment and avoid duplicated efforts.
  • Update Proactively: Communicate any challenges or delays you encounter.

Collaboration

  • Participate in Reviews: Review other contributors' PRs when possible. Constructive feedback strengthens the project and fosters collaboration.
  • Be Respectful: Treat all contributors with respect and professionalism.

Documentation and Examples

We welcome improvements to project documentation:

  • Improve API Documentation: Make it beginner-friendly by adding clear, concise explanations.
  • Write Tutorials and Examples: Create tutorials or example programs showcasing common use cases of the library.
  • Add Docstrings: Contribute Doxygen docstrings for functions and classes.
  • Wiki Contributions: Add markdown files to the project wiki.

Coding Guidelines

Modern C++ Best Practices

  • Use RAII (Resource Acquisition Is Initialization)
  • Avoid raw pointers where possible; prefer smart pointers
  • Use STL containers effectively

Code Quality

  • Naming Conventions: Use meaningful names for variables, functions, and classes.
  • Code Formatting: Maintain consistent indentation (4 spaces per level recommended).
  • Documentation: Document all public-facing methods using comments or Doxygen docstrings.
  • Zero Warnings: Ensure code compiles without warnings.
  • Testing: Verify all tests pass before submitting a PR.

Thank you for contributing to CinderPeak! Your efforts help build a robust and reliable graph library for the community.