Skip to main content

​
Welcome Contributors

Thanks for your interest in contributing to Readme.so! This community-maintained project welcomes all types of contributions including new features, bug fixes, documentation improvements, and translations.
Readme.so is a community fork of the original readme.so by Katherine Oelsner, now maintained by Koushik Romel.

​
Ways to Contribute

​
Reporting Bugs

Found a bug? Help us fix it:
1

Check Existing Issues

Search the Issues page to see if the bug has already been reported.
2

Create a New Issue

If it hasn’t been reported, create a new issue with:
  • Clear title - Summarize the problem
  • Steps to reproduce - Exact steps to trigger the bug
  • Expected behavior - What should happen
  • Actual behavior - What actually happens
  • Screenshots - If applicable
  • Environment - Browser, OS, device type

​
Suggesting Features

Have an idea for a new feature?
1

Open a Feature Request

Create a feature request issue to discuss your idea.
2

Wait for Feedback

Discuss with maintainers to ensure your effort aligns with the project roadmap before starting work.
Always discuss major features before implementing them to avoid wasted effort on changes that might not be accepted.

​
Improving Documentation

Documentation improvements are always welcome:
  • Fix typos or unclear explanations
  • Add missing documentation
  • Improve code examples
  • Translate to new languages

​
Development Workflow

​
1. Fork and Clone

# Visit https://github.com/koushikromel/readme-so-community/fork
# Click "Create fork"

​
2. Set Up Development Environment

# Install dependencies
npm install

# Start development server
npm run dev
See the Local Setup guide for detailed instructions.

​
3. Create a Feature Branch

Always create a new branch for your changes. Never commit directly to main.
# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Examples:
git checkout -b feature/add-badges-section
git checkout -b fix/drag-drop-mobile
git checkout -b docs/update-contributing
Branch Naming Conventions:
  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation updates
  • refactor/ - Code refactoring
  • test/ - Test additions or fixes

​
4. Make Your Changes

Follow these guidelines when making changes:

​
Code Style

The project enforces code style through ESLint and Prettier: 
# Check for issues
npm run lint

# Auto-fix formatting issues
npm run format
Configure your editor to run Prettier on save to avoid formatting issues.
Key Style Points:
  • Use functional components with hooks
  • Prefer const over let
  • Use meaningful variable names
  • Keep components small and focused
  • Add comments for complex logic

​
Component Guidelines

When creating or modifying components: 
// Good: Descriptive name, clear purpose
export const SectionFilter = ({ searchFilter, setSearchFilter }) => {
  // Component logic
}

// Bad: Vague name, too many responsibilities
export const Thing = (props) => {
  // Too much logic
}
Best Practices:
  • Keep components under 300 lines
  • Extract reusable logic into hooks
  • Use prop destructuring
  • Include PropTypes or TypeScript types (future)
  • Test user-facing components

​
State Management

Follow the existing patterns: 
// Lift state to common ancestor
const [selectedSections, setSelectedSections] = useState([])

// Pass down via props
<SectionsColumn 
  selectedSections={selectedSections}
  setSelectedSections={setSelectedSections}
/>

// Use localStorage for persistence
useEffect(() => {
  localStorage.setItem('key', JSON.stringify(value))
}, [value])

​
5. Test Your Changes

All changes must pass existing tests. New features should include tests.
# Run all tests
npm test

# Run tests in watch mode
npm test:watch

# Run tests with coverage
npm test -- --coverage
Manual Testing Checklist:
  • ✅ Editor loads without errors
  • ✅ Can add/remove sections
  • ✅ Can edit section content
  • ✅ Can drag and drop sections
  • ✅ Preview updates in real-time
  • ✅ Works on mobile devices
  • ✅ Dark mode works correctly
  • ✅ No console errors or warnings

​
6. Build and Verify

Before submitting, ensure the project builds successfully: 
# Create production build
npm run build

# Test production build locally
npm start
Production builds may reveal issues not present in development mode.

​
7. Commit Your Changes

Write clear, descriptive commit messages: 
git commit -m "Add badges section template"
git commit -m "Fix drag and drop on mobile devices"
git commit -m "Update contributing documentation"
Commit Message Format: 
<type>: <short description>

[optional body]
[optional footer]
Types:
  • feat - New feature
  • fix - Bug fix
  • docs - Documentation changes
  • style - Formatting, missing semicolons, etc.
  • refactor - Code restructuring
  • test - Adding tests
  • chore - Maintenance tasks

​
8. Push to Your Fork

# Push your branch to your fork
git push origin feature/your-feature-name

​
9. Open a Pull Request

1

Navigate to the Repository

Go to the main repository on GitHub.
2

Click 'New Pull Request'

GitHub will detect your recently pushed branch and show a prompt to create a PR.
3

Fill Out PR Template

Provide a clear title and description:Title: Brief summary of changes (e.g., “Add badges section template”)Description:
  • What changes were made
  • Why the changes were necessary
  • How to test the changes
  • Screenshots (if UI changes)
  • Related issue numbers
4

Submit and Wait for Review

A maintainer will review your PR. Be responsive to feedback and requests for changes.

​
Pull Request Guidelines

​
PR Checklist

Before submitting, ensure:
  • Code follows project style (passes npm run lint)
  • All tests pass (npm test)
  • Project builds successfully (npm run build)
  • Changes are well-documented in code comments
  • No console errors or warnings
  • Tested on both desktop and mobile
  • Tested in both light and dark modes
  • PR description clearly explains changes

​
Review Process

1

Automated Checks

GitHub Actions will run automated tests and linting. All checks must pass.
2

Maintainer Review

A maintainer will review your code, typically within a few days.
3

Address Feedback

Make requested changes by pushing new commits to your branch.
# Make changes based on feedback
git add .
git commit -m "Address PR feedback"
git push
4

Approval and Merge

Once approved, a maintainer will merge your PR. Congratulations!
Be patient and respectful during the review process. Maintainers are volunteers reviewing contributions in their spare time.

​
Code of Conduct

Please be respectful and considerate of others when contributing to this project. We strive to create a welcoming environment for everyone. Expected Behavior:
  • Be respectful of differing opinions and experiences
  • Accept constructive criticism gracefully
  • Focus on what’s best for the community
  • Show empathy towards other contributors
Unacceptable Behavior:
  • Trolling, insulting comments, or personal attacks
  • Public or private harassment
  • Publishing others’ private information
  • Other unprofessional conduct

​
Getting Help

Need help contributing?

Join Discussions

Ask questions in GitHub Discussions

Contact Maintainer

Reach out on Twitter/X

​
Recognition

All contributors are recognized in:
  • GitHub’s contributors graph
  • Release notes (for significant contributions)
  • The project’s community
Every contribution, no matter how small, is valuable and appreciated!

​
Next Steps

Local Setup

Set up your development environment

Architecture

Understand the codebase structure

Testing

Learn how to write tests

View Issues

Find issues to work on
Thank you for contributing to Readme.so! Your efforts help make this tool better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us