Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
334 lines (242 loc) · 8.44 KB

CONTRIBUTING.md

File metadata and controls

334 lines (242 loc) · 8.44 KB

Contributing to Open Browser Rendering

English | Bahasa Indonesia

First off, thank you for considering contributing to Open Browser Rendering! It's people like you that make this project a great tool for 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. Please report unacceptable behavior to the project maintainers.

Our Standards

  • Be respectful - Treat everyone with respect and kindness
  • Be collaborative - Work together and help each other
  • Be inclusive - Welcome newcomers and diverse perspectives
  • Be professional - Keep discussions focused and constructive

🤝 How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

Bug Report Template:

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Send request to '...'
2. With payload '...'
3. See error

**Expected behavior**
A clear description of what you expected to happen.

**Environment:**
 - OS: [e.g. Ubuntu 22.04]
 - Node.js version: [e.g. 18.17.0]
 - Docker version (if applicable): [e.g. 24.0.5]
 - Browser engine: [e.g. chromium]

**Additional context**
Add any other context about the problem here.

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:

Enhancement Template:

**Is your feature request related to a problem?**
A clear description of the problem.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Any alternative solutions or features you've considered.

**Additional context**
Any other context or screenshots about the feature request.

Pull Requests

  1. Fork the repository and create your branch from main
  2. Make your changes following our coding guidelines
  3. Test your changes thoroughly
  4. Update documentation if needed
  5. Submit a pull request with a clear description

Pull Request Template:

**Description**
Brief description of what this PR does.

**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 to verify 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 tested my changes locally

🛠️ Development Setup

Prerequisites

  • Node.js >= 18.0.0
  • npm or yarn
  • Git

Setup Steps

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/OpenBrowserRendering.git
cd OpenBrowserRendering

# 2. Install dependencies
npm install

# 3. Copy environment file
cp .env.example .env

# 4. Edit .env with your settings
# Set RENDERER_API_KEY to a test value

# 5. Start development server
npm run dev

# 6. Test the API
curl http://localhost:3000/health

Project Structure

OpenBrowserRendering/
├── server.js           # Main server file
├── package.json        # Dependencies and scripts
├── Dockerfile          # Docker configuration
├── docker-compose.yml  # Docker Compose setup
├── .env.example        # Environment variables template
├── README.md           # Documentation (English & Indonesian)
├── CONTRIBUTING.md     # This file
├── CONTRIBUTING.id.md  # Indonesian version
└── LICENSE             # MIT License

📝 Coding Guidelines

JavaScript Style

  • Use ES6+ features (const/let, arrow functions, async/await)
  • Use 2 spaces for indentation
  • Use single quotes for strings
  • Add semicolons at the end of statements
  • Use meaningful variable names
  • Add comments for complex logic

Example:

// Good ✅
async function getBrowser() {
  if (browser) return browser;
  const engine = (BROWSER_ENGINE || 'chromium').toLowerCase();
  
  // Launch browser based on selected engine
  if (engine === 'firefox') {
    browser = await firefox.launch({ 
      headless: true, 
      args: ['--no-sandbox'] 
    });
  }
  
  return browser;
}

// Bad ❌
async function getBrowser(){
    if(browser) return browser
    var engine=(BROWSER_ENGINE||'chromium').toLowerCase()
    if(engine==='firefox'){
        browser=await firefox.launch({headless:true,args:['--no-sandbox']})
    }
    return browser
}

Error Handling

  • Always use try-catch for async operations
  • Return meaningful error messages
  • Log errors with context
try {
  const result = await page.screenshot(opts);
  return result;
} catch (err) {
  console.error('Screenshot error:', err.message);
  return c.json({ error: err.message }, 500);
}

💬 Commit Messages

Follow the Conventional Commits specification:

Format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

feat(screenshot): add support for WebP format

Add WebP screenshot format support with quality control.
Closes #123

---

fix(pdf): handle timeout errors gracefully

Improve error handling for PDF generation timeouts.
Add retry logic for network errors.

---

docs(readme): update deployment instructions

Add detailed VPS deployment guide with Nginx configuration.

🧪 Testing

Manual Testing

Test all endpoints before submitting:

# Health check
curl http://localhost:3000/health

# Screenshot
curl -X POST http://localhost:3000/screenshot \
  -H "Authorization: Bearer supersecret123" \
  -H "Content-Type: application/json" \
  -o test.png \
  -d '{"url": "https://example.com"}'

# PDF
curl -X POST http://localhost:3000/pdf \
  -H "Authorization: Bearer supersecret123" \
  -H "Content-Type: application/json" \
  -o test.pdf \
  -d '{"url": "https://example.com"}'

# Evaluate
curl -X POST http://localhost:3000/evaluate \
  -H "Authorization: Bearer supersecret123" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "script": "document.title"}'

Docker Testing

# Build and test Docker image
docker build -t open-browser-rendering-test .
docker run -p 3000:3000 -e RENDERER_API_KEY=test123 open-browser-rendering-test

# Test with Docker Compose
docker-compose up --build

🎯 Areas for Contribution

We especially welcome contributions in these areas:

  • 🧪 Testing - Add unit tests and integration tests
  • 📚 Documentation - Improve docs, add examples, fix typos
  • 🐛 Bug Fixes - Fix reported issues
  • ✨ Features - Add new rendering options or formats
  • 🔒 Security - Improve security measures
  • ⚡ Performance - Optimize rendering speed and resource usage
  • 🌐 Internationalization - Add more language translations
  • 🎨 Examples - Create example implementations

📞 Questions?

🙏 Thank You!

Your contributions make this project better for everyone. We appreciate your time and effort!

Happy Contributing! 🚀

Made with ❤️ by DEVMODE Community