CONTRIBUTING.MD

Overview

The `CONTRIBUTING.MD` file provides guidelines and instructions for contributors who want to participate in the development of the ShapeShift Unchained project. It sets expectations about the types of contributions accepted, the process for submitting issues and pull requests (PRs), and the review and acceptance workflow. This document helps maintain code quality, streamline collaboration, and ensure that contributions align with the project’s standards and security policies.

Detailed Explanation

This file is a markdown document focused on community contribution policies rather than executable code. It contains several key sections, each outlining important rules and workflows.

Sections and Their Purposes

1. Typo-Only Changes Not Accepted

• Purpose: To inform contributors that pull requests or issues solely fixing typos in comments, variables, or documentation will not be reviewed or merged.

• Reason: This policy helps maintain focus on meaningful changes and reduces maintainers' overhead.

2. Submitting an Issue

• Important Note: Contributors should not open GitHub issues for security vulnerabilities.

  • Instead, they should use the ShapeShift responsible disclosure program.

• Process: Contributors should discuss proposed changes via GitHub issues before submitting pull requests.

• Usage: Helps ensure that changes are agreed upon before implementation, avoiding duplicated effort or conflicting code.

3. Submitting a Patch (Pull Request)

• Process:

  • Open a pull request with the proposed patch.

  • Provide a clear PR description explaining the problem and how the patch solves it.

  • Link the PR to an existing issue if applicable.

• Style Guidelines:

  • Whitespace or formatting-only changes are generally discouraged unless part of a larger functional change.

  • Style fixes should be in separate commits from functional changes.

• Testing:

  • Contributors are encouraged to add unit or integration tests that verify new functionality.

• Usage: Ensures PRs are well-documented, focused, and tested, improving codebase quality.

4. Getting Your PR Accepted

• Review Process: Maintainers aim to review PRs promptly but ask contributors to be patient.

• Approval Requirements: At least one ShapeShift Fox (trusted maintainer) must sign off on the PR.

• Commit Signing: Contributors who use GPG are encouraged to sign commits for authenticity.

• Merging: After acceptance, contributors may merge their patch.

• Closing Note: Ends on a friendly note encouraging contributors to enjoy participating.

Implementation Details

• The file is purely instructional/documentation in markdown format.

• It uses markdown headings, bullet points, and links for clarity and easy navigation.

• No algorithms or code logic are involved.

• References external resources such as the responsible disclosure program link.

• Emphasizes best practices for collaborative development, issue management, and code review.

Interaction with Other Parts of the System

• This file is part of the repository’s root or documentation folder and serves as a contributor-facing guide.

• It interacts indirectly by setting rules that contributors must follow when submitting code or issues to the source code files and project workflow.

• It complements other documentation such as README.md, CODE_OF_CONDUCT.md, and SECURITY.md by focusing on contribution procedures.

• It ensures that contributions to the application’s codebase, tests, and documentation adhere to agreed standards and processes.

Usage Example

When a developer wants to fix a bug or add a feature:

1. They first check CONTRIBUTING.MD for the process.

2. They open a GitHub issue to discuss the change, unless it’s a security vulnerability.

3. After discussion and approval, they create a branch, implement the fix/feature, and add tests.

4. They open a PR referencing the issue, describing the problem and solution.

5. Maintainers review, request changes if needed, and sign off.

6. The contributor merges the PR once accepted.

This process reduces miscommunication and improves project quality.

Visual Diagram

Below is a flowchart illustrating the contribution workflow as described in `CONTRIBUTING.MD`.

flowchart TD
    A[Start: Contributor wants to contribute] --> B{Is it a security vulnerability?}
    B -- Yes --> C[Do NOT open GitHub issue]
    C --> D[Use responsible disclosure program]
    B -- No --> E[Open GitHub issue to discuss change]
    E --> F[Create a patch / feature branch]
    F --> G[Implement changes and add tests]
    G --> H[Open Pull Request with description and issue link]
    H --> I{Maintainer reviews PR}
    I -- Request changes --> G
    I -- Approved --> J[ShapeShift Fox signs off PR]
    J --> K[Contributor merges PR]
    K --> L[Contribution complete]

Summary

`CONTRIBUTING.MD` is a crucial documentation file that governs how contributors engage with the ShapeShift Unchained project. It defines policies to ensure security, quality, and effective collaboration. By following this guide, contributors help maintain the integrity and progress of the software while benefiting from a structured and supportive contribution process.