rss-proxy 0.2.0

A high-performance, extensible RSS/Atom proxy and filtering server written in Rust
Documentation
# Contributing to RSS Proxy

Thank you for your interest in contributing to RSS Proxy! This document provides guidelines and instructions for contributing to the project.

## Table of Contents

- [Code of Conduct]#code-of-conduct
- [Getting Started]#getting-started
- [Development Setup]#development-setup
- [Running Tests]#running-tests
- [Code Style]#code-style
- [Submitting a Pull Request]#submitting-a-pull-request
- [Adding New Plugins]#adding-new-plugins

---

## Code of Conduct

This project adheres to a code of conduct that expects all contributors to be respectful, inclusive, and professional. Please be courteous and constructive in all interactions.

---

## Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally:
   ```bash
   git clone https://github.com/<your-username>/rss-proxy.git
   cd rss-proxy
   ```
3. Add the upstream remote:
   ```bash
   git remote add upstream https://github.com/rust-rss-proxy/rss-proxy.git
   ```

---

## Development Setup

### Prerequisites

- Rust 1.75 or later ([rustup.rs]https://rustup.rs/)
- Cargo (included with Rust)
- A modern web browser for testing the proxy server

### Building from Source

```bash
# Build the project
cargo build

# Build for release
cargo build --release
```

### Running the Server Locally

```bash
# Start with default config
cargo run -- serve

# Start with custom config and port
cargo run -- serve --config config.yaml --port 3000 --host 127.0.0.1
```

---

## Running Tests

Before submitting a pull request, ensure all tests pass:

```bash
# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run tests in release mode
cargo test --release

# Run specific test
cargo test <test_name>
```

### Testing Plugins

To test custom Rhai plugins:

```bash
# Start server with plugins directory
cargo run -- serve --config config.yaml

# Test plugin endpoints
curl http://localhost:8080/plugins
```

---

## Code Style

### Rust Formatting

We use `rustfmt` for code formatting. Please format your code before submitting:

```bash
cargo fmt --all
```

### Clippy Lints

Run clippy to catch common pitfalls and improve code quality:

```bash
cargo clippy --all-targets --all-features -- -D warnings
```

### Commit Message Format

We follow conventional commit messages:

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

<body>

<footer>
```

Types include:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding or modifying tests
- `chore`: Maintenance tasks

Example:
```
feat(filters): add max_age_days filter support

Implemented the max_age_days filter option in FeedFilterConfig
to allow filtering items by their publication age.

Closes #123
```

---

## Submitting a Pull Request

1. Ensure your branch is up-to-date with `upstream/main`:
   ```bash
   git fetch upstream
   git rebase upstream/main
   ```

2. Make sure all tests pass and code is formatted:
   ```bash
   cargo test
   cargo fmt --all
   cargo clippy --all-targets --all-features -- -D warnings
   ```

3. Push your branch to your fork:
   ```bash
   git push origin <branch-name>
   ```

4. Open a pull request on GitHub, referencing any related issues.

---

## Adding New Plugins

RSS Proxy supports two types of plugins:

### Built-in Plugins (Rust)

To add a new built-in plugin:

1. Create a new module in `src/plugin/builtin/`
2. Implement the `Plugin` trait from `src/plugin/mod.rs`
3. Register the plugin in `src/plugin/builtin/mod.rs`
4. Add tests for your plugin

### Rhai Script Plugins

To add a new Rhai script plugin:

1. Create a `.rhai` file in the `plugins/` directory
2. Export functions with the `export` keyword
3. Functions should accept `item` (feed item) and return `item` or `null` (to filter out)

Example plugin structure:

```rhai
// plugins/my_custom_filter.rhai

export function filter_spam(item) {
    let spam_words = ["viagra", "casino", "lottery"];
    for word in spam_words {
        if item.title.contains(word) || item.content.contains(word) {
            return null; // Filter out this item
        }
    }
    return item; // Keep this item
}
```

---

## Questions?

If you have questions or need help, please:

1. Check existing issues and pull requests
2. Open a new issue with the `question` label
3. Reach out to the maintainers

Thank you for contributing to RSS Proxy!