Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
279 lines (200 loc) · 7.66 KB

CONTRIBUTING.md

File metadata and controls

279 lines (200 loc) · 7.66 KB
Raw

Contributing to OSV Framework

Thank you for your interest in contributing to the Open Sponsor Value (OSV) Framework! We welcome contributions from everyone.

Table of Contents

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

How to Contribute

Reporting Bugs

  • Check if the issue has already been reported
  • Use the issue template if available
  • Provide clear steps to reproduce
  • Include relevant details (OS, version, etc.)

Suggesting Enhancements

  • Check if the enhancement has been suggested before
  • Clearly describe the feature and its benefits
  • Explain why this would be valuable to the OSV Framework

Contributing Code or Documentation

  1. Fork the repository
  2. Create a new branch from main
  3. Make your changes
  4. Follow our commit convention (see below)
  5. Submit a pull request

Git Commit Convention

We follow the Clean Commit convention for all commit messages. This provides clarity and visual recognition through emoji-based commit types.

Format

<emoji> <type>: <description>
<emoji> <type>(<scope>): <description>

Rules

  • Use lowercase for type
  • Use present tense ("add" not "added")
  • No period at the end
  • Keep description under 72 characters

Commit Types

This project follows the Clean Commit convention.

Emoji Type What it covers Example
📦 new Adding new features, files, or capabilities 📦 new: add fibonacci breakdown guide
🔧 update Changing existing code, refactoring, improvements 🔧 update: improve calculation methodology
🗑️ remove Removing code, files, features, or dependencies 🗑️ remove: unused example files
🔒 security Security fixes, patches, vulnerability resolutions 🔒 security: patch XSS vulnerability
⚙️ setup Project configs, CI/CD, tooling, build systems ⚙️ setup: add github actions workflow
☕ chore Maintenance tasks, dependency updates, housekeeping ☕ chore: update dependencies
🧪 test Adding, updating, or fixing tests 🧪 test: add calculation tests
📖 docs Documentation changes and updates 📖 docs: update readme with examples
🚀 release Version releases and release preparation 🚀 release: version 1.0.0

Examples

Good Commit Messages

📦 new: add fibonacci breakdown guide
🔧 update: improve calculation methodology
📖 docs: update readme with framework overview
🗑️ remove: unused example files
🔒 security: patch XSS vulnerability
⚙️ setup: add github actions workflow
☕ chore: update dependencies
🧪 test: add calculation tests
🚀 release: version 1.0.0

Bad Commit Messages

# Too vague
update files

# No emoji or context
added new feature

# Wrong format
docs/fix: multiple contexts

Detailed Commit Messages

For complex changes, use a detailed format:

emoji <context>: short summary (50 chars or less)

More detailed explanation of the change. Wrap at 72 characters.
Explain the problem this commit solves and why this approach
was chosen.

- Bullet points are acceptable
- Use present tense: "add" not "added"
- Reference issues: Closes #123

Example:

📦 new: add project pricing example

Adds a comprehensive example showing how to implement OSV pricing
for a complete project. Includes issue backlog estimation,
sponsorship tiers, and public tracking dashboard.

- Complete project example with real scenarios
- Pricing table for backlog items
- Monthly update template
- GitHub integration examples

Closes #15

Writing Commit Messages

  1. Use the imperative mood: "add" not "added" or "adds"
  2. Capitalize the first letter after the context
  3. No period at the end of the summary
  4. Keep summary under 50 characters (emoji and context included)
  5. Separate subject from body with a blank line
  6. Wrap body at 72 characters
  7. Reference issues using "Closes #123" or "Fixes #123"

Using Emojis

You can type emojis directly or use emoji codes:

# Direct emoji (copy-paste)
git commit -m "📦 new: add new feature"

# Using emoji code (if your terminal/editor supports it)
git commit -m ":package: new: add new feature"

Most modern terminals and editors support direct emoji input:

  • macOS: Control + Command + Space
  • Windows: Windows + . (period)
  • Linux: Ctrl + Shift + E (in many apps)

Pull Request Process

  1. Create a descriptive PR title using the same emoji convention:

    📦 new: add calculation examples

  2. Fill out the PR template completely:

    • Describe your changes
    • Link related issues
    • List testing performed
    • Note any breaking changes

  3. Ensure all checks pass:

    • No merge conflicts
    • Documentation is up-to-date
    • Style guidelines followed

  4. Request review from maintainers

  5. Address feedback promptly and professionally

  6. Update your branch if needed:

    git fetch origin
git rebase origin/main

Development Setup

Prerequisites

  • Git
  • Text editor (VS Code, Vim, etc.)
  • Markdown preview tool (optional)

Getting Started

  1. Fork and clone the repository:

    git clone https://github.com/YOUR-USERNAME/osv-framework.git
cd osv-framework

  2. Create a new branch:

    git checkout -b new/your-feature-name

  3. Make your changes

  4. Commit with proper format:

    git commit -m "📦 new: your feature description"

  5. Push to your fork:

    git push origin feat/your-feature-name

  6. Open a pull request

Documentation Guidelines

Markdown Style

  • Use ATX-style headers (# not underlines)
  • Use fenced code blocks with language specification
  • Keep line length reasonable (80-100 characters for prose)
  • Use relative links for internal documentation
  • Include a table of contents for long documents

Writing Style

  • Be clear and concise
  • Use examples to illustrate concepts
  • Write for beginners but don't oversimplify
  • Use active voice ("calculate the value" not "the value is calculated")
  • Be consistent with terminology

Documentation Structure

docs/
  ├── getting-started.md    # Introduction and basics
  ├── calculation-guide.md  # Detailed methodology
  └── ...                   # Additional guides

examples/
  ├── README.md            # Overview of examples
  ├── issue-template.md    # Practical templates
  └── ...                  # More examples

Getting Help

  • Questions? Open a discussion in the repository
  • Bug? Create an issue with details
  • Feature idea? Open an issue for discussion first
  • Stuck? Ask for help in your pull request

Recognition

All contributors will be recognized in our documentation. Thank you for helping make the OSV Framework better!

License

By contributing to OSV Framework, you agree that your contributions will be licensed under the GNU General Public License v3.0.

Thank you for contributing to OSV Framework! 🙏

Your efforts help make open source sponsorship more transparent and fair for everyone.