Contributing

Guidelines for contributing to Orphelix - code, documentation, and community

Welcome Contributors!

Thank you for your interest in contributing to Orphelix! We welcome contributions from everyone, whether you’re fixing a typo, adding a feature, or improving documentation.

Before contributing, please read our Code of Conduct.

Ways to Contribute

Code

Fix bugs, add features, improve performance

Documentation

Improve docs, add examples, fix typos

Testing

Write tests, report bugs, test features

Design

UI/UX improvements, accessibility

Getting Started

1. Fork and Clone

1. Fork repository

   Click “Fork” on GitHub

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/orphelix.git
   cd orphelix/app
   
3. Add upstream remote

   git remote add upstream https://github.com/corapoid/orphelix.git
   git fetch upstream
   
4. Install dependencies

   npm install
   
5. Start development

   npm run dev
   

2. Find Something to Work On

Good First Issues

Look for issues labeled good first issue

These are:

• Well-documented
• Not too complex
• Great for beginners
• Have clear acceptance criteria

Help Wanted

Check help wanted label

These are:

• Higher priority
• Need community help
• May require more experience
• Important for project goals

Propose New Feature

Have an idea? Create a discussion:

1. Go to Discussions
2. Click “New discussion”
3. Choose “Ideas” category
4. Describe your feature
5. Wait for feedback

3. Claim an Issue

Comment on the issue:

I’d like to work on this issue. Could you assign it to me?

Wait for confirmation before starting work.

Development Workflow

Create Feature Branch

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/bug-description

Branch naming conventions:

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation changes
• refactor/ - Code refactoring
• test/ - Test improvements
• chore/ - Build, dependencies, etc.

Make Changes

Follow our coding standards:

Code Style

TypeScript:

• Use TypeScript for all new code
• Avoid any type
• Add JSDoc comments for public APIs

Formatting:

• Prettier handles formatting (runs on save)
• 2 spaces for indentation
• Single quotes for strings
• Semicolons optional

Naming:

• camelCase for variables and functions
• PascalCase for components and types
• UPPER_SNAKE_CASE for constants
• kebab-case for file names

React/Next.js

Components:

• Use functional components with hooks
• Prefer named exports over default exports
• Keep components under 300 lines
• Extract reusable logic to custom hooks

Hooks:

• Name custom hooks use*
• Keep hooks under 150 lines
• Use TanStack Query for data fetching
• Use Zustand for global state

Files:

• One component per file
• Co-locate types with components
• Use @/ path alias for imports

API Routes

Structure:

• One route per file
• Export named functions (GET, POST, etc.)
• Keep routes under 200 lines
• Extract business logic to lib/

Error Handling:

• Always try-catch async operations
• Return appropriate HTTP status codes
• Include error messages in response
• Log errors for debugging

Example:

export async function GET(request: NextRequest) {
  try {
    const data = await fetchData()
    return Response.json(data)
  } catch (error) {
    console.error('[API] Error:', error)
    return Response.json(
      { error: error.message },
      { status: 500 }
    )
  }
}

Testing

Required:

• Add unit tests for new features
• Add E2E tests for user flows
• Ensure all tests pass before PR

Coverage:

• Aim for 80%+ coverage
• Test edge cases and errors
• Mock external dependencies

Run tests:

npm test
npm run test:e2e

Commit Your Changes

Follow Conventional Commits:

git add .
git commit -m "type(scope): description"

Commit types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• style: - Code style (formatting, semicolons, etc.)
• refactor: - Code change that neither fixes bug nor adds feature
• perf: - Performance improvement
• test: - Adding or updating tests
• chore: - Build process, dependencies, etc.

Examples:

git commit -m "feat(deployments): add restart all button"
git commit -m "fix(pods): correct log streaming memory leak"
git commit -m "docs(readme): update installation instructions"
git commit -m "test(api): add deployment endpoint tests"
git commit -m "chore(deps): upgrade react to 19.0.1"

Push Changes

git push origin feature/your-feature-name

Pull Request Process

1. Create Pull Request

Go to your fork on GitHub and click “New pull request”

PR Title: Follow conventional commit format:

feat(deployments): add restart all button

PR Description Template:

## Description
Brief description of the changes

## Related Issue
Closes #123

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How Has This Been Tested?
Describe the tests you ran

## Screenshots (if applicable)
Add screenshots to help explain your changes

## Checklist
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published

2. Code Review

What reviewers look for:

• Code quality and readability
• Test coverage
• Documentation updates
• Breaking changes
• Performance implications
• Security concerns

Responding to feedback:

1. Make requested changes
2. Push to same branch (PR updates automatically)
3. Respond to comments
4. Mark conversations as resolved

3. CI Checks

Automated checks that must pass:

• TypeScript compilation
• ESLint (no errors)
• Unit tests
• E2E tests
• Build succeeds

If CI fails:

# Run checks locally
npm run type-check
npm run lint
npm test
npm run build

Fix issues and push again.

4. Merge

Once approved and CI passes:

• Maintainer will merge your PR
• Your branch will be deleted
• Congratulations! 🎉

Code Review Guidelines

For Contributors

Self-Review

Before requesting review:

• Read your own code
• Check for typos
• Remove debug code
• Add comments where needed
• Update documentation

Be Patient

Maintainers review PRs in their free time. It may take a few days.

Be Responsive

Respond to feedback within a week. PRs may be closed if inactive for >2 weeks.

Be Respectful

Feedback is about the code, not you. Stay professional and courteous.

For Reviewers

What to Check

• Code correctness
• Test coverage
• Documentation
• Performance
• Security
• Accessibility

Feedback Style

• Be specific and constructive
• Explain the “why”
• Suggest alternatives
• Praise good work
• Use “we” not “you”

Response Time

• Review within 1-2 days if possible
• Leave comment if you need more time
• Request changes or approve clearly

Documentation

When to Update Docs

Update documentation when you:

• Add new feature
• Change existing behavior
• Add new API endpoint
• Modify configuration
• Update dependencies

Documentation Locations

docs/
├── user/              # User-facing docs
│   ├── *.mdx         # Feature guides
│   ├── github/       # GitHub integration
│   └── configuration/ # Settings
│
└── developer/         # Developer docs
    ├── *.mdx         # Dev guides
    └── api/          # API reference

Writing Good Docs

Style

• Clear and concise
• Active voice
• Short sentences
• Examples with code
• Screenshots when helpful

Structure

• Start with overview
• Prerequisites section
• Step-by-step instructions
• Troubleshooting section
• Next steps / related pages

Code Examples

• Include complete examples
• Add comments
• Show input and output
• Use realistic data
• Test all examples

Reporting Bugs

Before Reporting

1. Search existing issues - Check if already reported
2. Update to latest - Bug may be fixed
3. Test in demo mode - Isolate from cluster issues
4. Reproduce consistently - Document exact steps

Bug Report Template

**Describe the bug**
A clear description of what the bug is

**To Reproduce**
Steps to reproduce:
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

**Expected behavior**
What you expected to happen

**Screenshots**
If applicable, add screenshots

**Environment:**
- OS: [e.g. macOS 14.0]
- Browser: [e.g. Chrome 120]
- Node version: [e.g. 20.11.0]
- Orphelix version: [e.g. 0.1.0]
- Kubernetes version: [e.g. 1.28.0]
- Cluster type: [e.g. Minikube, AWS EKS]

**Additional context**
Any other context about the problem

**Logs**

Paste relevant logs here

Suggesting Features

Feature Request Template

**Is your feature request related to a problem?**
Describe the problem you're trying to solve

**Describe the solution you'd like**
Clear description of what you want to happen

**Describe alternatives you've considered**
Other solutions or features you've considered

**Use cases**
Who would use this feature and how?

**Additional context**
Mockups, screenshots, or examples

Community Guidelines

Code of Conduct

We follow the Contributor Covenant:

• Be respectful and inclusive
• Welcome newcomers
• Focus on what’s best for the community
• Show empathy towards others
• Accept constructive criticism gracefully

Communication Channels

GitHub Issues

Bug reports and feature requests

GitHub Discussions

General questions and ideas

Discord

Real-time chat (coming soon)

Twitter

Updates and announcements

Getting Help

I have a question

Ask in GitHub Discussions

I found a bug

Create an issue

I have an idea

Start a discussion

I need dev help

Ask in Discord or Discussions

Recognition

Contributors

All contributors are recognized in:

• CONTRIBUTORS.md
• GitHub contributors page
• Release notes

Types of Contributions

We recognize all contributions:

• Code (features, fixes, refactoring)
• Documentation (guides, API docs, examples)
• Testing (writing tests, reporting bugs)
• Design (UI/UX, logos, screenshots)
• Community (answering questions, mentoring)
• Infrastructure (CI/CD, deployments)

Becoming a Maintainer

Active contributors may be invited to become maintainers:

Criteria:

• 10+ merged PRs
• 3+ months of active contribution
• Good understanding of codebase
• Helpful to community
• Follows guidelines

Responsibilities:

• Review PRs
• Triage issues
• Mentor contributors
• Maintain code quality

Advanced Topics

Working with Forks

Keep fork updated:

# Fetch upstream changes
git fetch upstream

# Merge into main
git checkout main
git merge upstream/main

# Push to fork
git push origin main

Rebase feature branch:

git checkout feature/my-feature
git rebase main

# If conflicts, resolve and continue
git rebase --continue

# Force push (your feature branch only!)
git push --force-with-lease origin feature/my-feature

Draft Pull Requests

Create draft PR for work in progress:

1. Open PR as normal
2. Click “Create draft pull request”
3. Mark ready for review when done

Benefits:

• Get early feedback
• Show progress
• Run CI checks
• Collaborate with others

Multiple Commits in PR

Option 1: Squash before merge

• GitHub can squash on merge
• All commits become one
• Clean history

Option 2: Keep separate commits

• Each commit is meaningful
• Good commit messages
• Logical progression

Co-authoring Commits

Give credit to collaborators:

git commit -m "feat: add feature

Co-authored-by: Name <[e-mail]>
Co-authored-by: Another Name <[e-mail]>"

Troubleshooting

Common Issues

Merge conflicts

# Update your branch with latest main
git fetch upstream
git checkout main
git merge upstream/main
git checkout feature/my-feature
git rebase main

# Resolve conflicts in editor
# Then continue
git add .
git rebase --continue

# Force push (your branch only!)
git push --force-with-lease origin feature/my-feature

CI failing

# Run checks locally
npm run type-check  # TypeScript
npm run lint        # ESLint
npm test            # Unit tests
npm run test:e2e    # E2E tests
npm run build       # Build

Tests failing

# Update snapshots
npm test -- -u

# Run specific test
npm test -- my-test.test.ts

# Debug test
npm test -- --inspect-brk

Can't push to main

Main branch is protected. Always work in feature branches:

git checkout -b feature/my-feature
# Make changes
git push origin feature/my-feature

Additional Resources

Getting Started

Set up development environment

Architecture

Understand system design

Testing Guide

Write and run tests

API Reference

API documentation

Thank You!

Thank you for contributing to Orphelix! Every contribution, no matter how small, makes a difference.

Questions? Ask in GitHub Discussions or create an issue.