Add a basic CONTRIBUTING.mdHEADmaster

1 files changed, 113 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3877ebf
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,113 @@
+# Contributing to oreilly-epub
+
+First off — thank you for your interest in contributing! \
+This document explains how to set up your environment, run checks/tests, make
+changes, and submit pull requests (PRs).
+
+> **License note:** By contributing, you agree that your contributions will be
+> licensed under the project's license (GPLv3). See `LICENSE.txt` in the repo.
+
+## Project goals
+
+This tool downloads an O'Reilly (Safari) book by ID and assembles a valid EPUB
+by fetching metadata/chapters/assets, cleaning up XHTML, injecting styles, and
+writing a standards-compliant archive. The pipeline includes:
+
+- Authenticated HTTP client using a user-provided `cookies.json`.
+- Parallel file downloads with configurable concurrency (default 4, max 8).
+- XHTML/OPF processing to ensure EPUB validity (e.g., void tags, stylesheet
+links, `dc:description` injection).
+- CI/CD pipelines that run `rustfmt`, `clippy`, tests, and build release
+artifacts on tag pushes.
+
+## Getting started
+
+### Prerequisites
+
+- **Rust toolchain** (stable) with `cargo`. The CI uses
+`dtolnay/rust-toolchain@stable`, so match stable locally.
+- For actual end-to-end runs: a **`cookies.json`** file (flat key-value JSON of
+cookies for `https://learning.oreilly.com`). Place it in one of:
+  1. `--cookies <path>` argument
+  2. `${XDG_CONFIG_HOME}/oreilly-epub/cookies.json`
+  3. the project's current directory (`./cookies.json`) \
+     The app will search these locations in this order.
+
+> **Note:** The app is asynchronous (Tokio) and uses `reqwest`. No special
+> services are required to build and run locally.
+
+### Repository layout (high-level)
+
+- `src/main.rs` – CLI, argument parsing, orchestration (fetch metadata, pages,
+downloads, build EPUB).
+- `src/http_client.rs` – authenticated client from `cookies.json`.
+- `src/epub.rs` – download pipeline and zip/EPUB creation (mimetype first,
+`META-INF/container.xml`, etc.).
+- `src/xml.rs` – XHTML/OPF rewriting (void tags, attribute rewrite, stylesheet
+linking, description injection).
+- `src/models.rs` – data models for APIs (EPUB, chapters, files, pagination).
+
+### Quick start
+
+```bash
+# 1) Clone
+git clone <REPO_URL>
+cd oreilly-epub
+
+# 2) (Optional) Place cookies.json (see above)
+# Example:
+# cp /path/to/cookies.json .
+
+# 3) Build
+cargo build
+
+# 4) Check format & lints locally
+cargo fmt --all
+cargo clippy --all-targets --all-features -- -D warnings
+
+# 5) Run unit tests
+cargo test --all
+
+# 6) Try it (example book id)
+cargo run -- 9781492097039 --parallel 4
+# Add --skip-download if you already have cached files
+# Add --cookies ./cookies.json to point to a specific file
+```
+
+## Development workflow
+
+### Style and linting
+
+- **Formatting:** `cargo fmt --all` (CI runs `cargo fmt --all -- --check`).
+- **Linting:** `cargo clippy --all-targets --all-features -- -D warnings` (CI
+treats warnings as errors).
+
+> PRs must pass both format and clippy checks locally before you push.
+
+## Before you open a PR
+
+### Commit messages
+
+- Use clear, imperative subject lines: “Fix EPUB container.xml path
+resolution”, not “fixed stuff”.
+- Wrap body lines at \~72 characters when practical.
+- Reference issues with `Fixes #123` / `Closes #123` when appropriate.
+
+### Branch naming
+
+Use short, descriptive branches, e.g.:
+
+- `feat/parallelism-8-limit`
+- `fix/xhtml-void-tags`
+- `docs/contributing`
+
+### Checklists
+
+Before pushing:
+
+- [ ] `cargo fmt --all` produces no diffs.
+- [ ] `cargo clippy --all-targets --all-features -- -D warnings` passes locally.
+- [ ] `cargo test --all` is green.
+- [ ] If you touched XML/OPF/XHTML handling, tested at least one real book
+locally (if possible).
+- [ ] Updated documentation, comments, or usage text when applicable.