From d3fa41584599814e4d1f37abca26613d31122490 Mon Sep 17 00:00:00 2001 From: GeiserX <9169332+GeiserX@users.noreply.github.com> Date: Tue, 29 Sep 2026 23:18:29 +0200 Subject: [PATCH 1/2] docs: fix the --max-depth flag and state the GPL license without a non-commercial clause README and usage.md cited --depth; the parser only knows --max-depth. The license section said the software is not for commercial use, which the GPL in LICENSE does not allow anyone to add; it is now one GPL-3.0-or-later line with an absolute link, since Docker Hub and PyPI both render this README. installation.md becomes getting-started.md with a pinned Docker image, ci.md folds into usage.md, the license badge is dynamic, and setup.py says GPL-3.0-or-later and ships the LICENSE file again (twine 7 accepts it). --- README.md | 17 +++++------ docs/ci.md | 61 --------------------------------------- docs/getting-started.md | 37 ++++++++++++++++++++++++ docs/installation.md | 39 ------------------------- docs/related.md | 3 +- docs/usage.md | 63 ++++++++++++++++++++++++++++++++++++++++- setup.py | 6 ++-- 7 files changed, 110 insertions(+), 116 deletions(-) delete mode 100644 docs/ci.md create mode 100644 docs/getting-started.md delete mode 100644 docs/installation.md diff --git a/README.md b/README.md index 75e836f..f62559f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- Wayback-Diff Banner + Wayback-Diff banner

@@ -10,7 +10,7 @@ PyPI Version CI - License: GPL-3.0 + License codecov

@@ -21,7 +21,7 @@ Comparing web pages gets hard once Wayback Machine injections, whitespace noise - Strips Wayback Machine banners, analytics and playback scripts, and URL rewrites, so you compare the real content. - Tags every change High, Medium or Low. - Screenshots in Chrome, Firefox, Edge and Opera, with side-by-side and pixel-diff images (`--visual`). -- Site-wide crawl and compare with `--traverse --depth N`. +- Site-wide crawl and compare with `--traverse --max-depth N`. - Text, JSON and unified diff output, plus Markdown reports (`--markdown`). - CI exit codes: `0` no changes, `1` low or medium, `2` high. - Installs from PyPI, from source or as a Docker image. @@ -33,19 +33,16 @@ pip install wayback-diff wayback-diff https://web.archive.org/web/20230101/https://example.com/ https://example.com/ ``` -Add `--visual --markdown` for screenshots and a report (`pip install wayback-diff[visual]` first). +Add `--visual --markdown` for screenshots and a report (`pip install "wayback-diff[visual]"` first). Needs Python 3.10 or newer; the source and Docker installs are in [Getting started](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/getting-started.md). ## Documentation -- [Installation](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/installation.md): PyPI, source, Docker -- [Usage](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/usage.md): options, visual comparison, Markdown reports, output formats -- [CI/CD integration](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/ci.md): exit codes, GitHub Actions and shell gates +- [Getting started](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/getting-started.md): PyPI, source, Docker +- [Usage](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/usage.md): options, visual comparison, Markdown reports, output formats, and CI/CD gates on the exit codes - [How it works](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/how-it-works.md): cleaning, significance scoring, comparison with similar tools - [Development](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/development.md): tests and contributing - [Related projects](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/related.md) ## License -This project is licensed under the **GNU General Public License v3.0** (GPL-3.0). See the [LICENSE](LICENSE) file for details. - -This software is **not** intended for commercial use. +[GPL-3.0-or-later](https://github.com/GeiserX/Wayback-Diff/blob/main/LICENSE) diff --git a/docs/ci.md b/docs/ci.md deleted file mode 100644 index ea83a8c..0000000 --- a/docs/ci.md +++ /dev/null @@ -1,61 +0,0 @@ -# CI/CD integration - -Wayback-Diff returns meaningful exit codes designed for pipeline gates: - -| Exit Code | Meaning | -|-----------|---------| -| `0` | No differences detected | -| `1` | Low or medium significance changes | -| `2` | High significance changes detected | - -## GitHub Actions example - -```yaml -name: Visual Regression Check -on: - pull_request: - -jobs: - diff: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: "3.11" - - - name: Install Wayback-Diff - run: | - pip install -r requirements.txt - pip install -e ".[visual]" - - - name: Compare staging vs production - run: | - wayback-diff \ - https://staging.example.com \ - https://production.example.com \ - --visual --markdown --format json -o diff.json - - - name: Upload report - if: always() - uses: actions/upload-artifact@v4 - with: - name: diff-report - path: reports/ -``` - -## Shell script gate - -```bash -wayback-diff "$OLD_URL" "$NEW_URL" --format json -o result.json -EXIT_CODE=$? - -if [ $EXIT_CODE -eq 2 ]; then - echo "BLOCKING: high-significance changes detected" - exit 1 -elif [ $EXIT_CODE -eq 1 ]; then - echo "WARNING: minor changes detected" -fi -``` diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..55d859b --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,37 @@ +# Getting started + +Wayback-Diff needs Python 3.10 or newer. + +## From PyPI + +```bash +pip install wayback-diff + +# With visual comparison support +pip install wayback-diff[visual] +``` + +## From source + +```bash +git clone https://github.com/GeiserX/Wayback-Diff.git +cd Wayback-Diff +python3 -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate +pip install -r requirements.txt +pip install -e . +``` + +For visual comparison support: + +```bash +pip install -e ".[visual]" +``` + +## Docker + +```bash +docker run --rm drumsergio/wayback-diff:1.1.0 https://example.com/a https://example.com/b +``` + +The image is built for `linux/amd64`; on Apple Silicon add `--platform linux/amd64`. To build the image from a checkout instead: `docker build -t wayback-diff .`, then `docker run --rm wayback-diff `. diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index f2e82a8..0000000 --- a/docs/installation.md +++ /dev/null @@ -1,39 +0,0 @@ -# Installation - -## From PyPI - -```bash -pip install wayback-diff - -# With visual comparison support -pip install wayback-diff[visual] -``` - -## From source - -```bash -git clone https://github.com/GeiserX/Wayback-Diff.git -cd Wayback-Diff -python3 -m venv venv -source venv/bin/activate # Windows: venv\Scripts\activate -pip install -r requirements.txt -pip install -e . -``` - -For visual comparison support: - -```bash -pip install -e ".[visual]" -``` - -## Docker - -```bash -docker build -t wayback-diff . -docker run --rm wayback-diff https://example.com/a https://example.com/b -``` - -## Supported versions - - Python Versions - Docker diff --git a/docs/related.md b/docs/related.md index 6b72c83..a401011 100644 --- a/docs/related.md +++ b/docs/related.md @@ -3,8 +3,7 @@ | Project | Description | |---------|-------------| | [Wayback-Archive](https://github.com/GeiserX/Wayback-Archive) | Download complete websites from the Wayback Machine with full asset preservation | -| [Wayback-Diff](https://github.com/GeiserX/Wayback-Diff) | Intelligent web page comparison tool with Wayback Machine support | | [Way-CMS](https://github.com/GeiserX/Way-CMS) | Simple web CMS for editing HTML/CSS files downloaded from Wayback Archive | | [web-mirror](https://github.com/GeiserX/web-mirror) | Mirror any webpage to a local server for offline access | | [media-download](https://github.com/GeiserX/media-download) | Download all media files from any web page into a folder schema | -| [n8n-nodes-way-cms](https://github.com/GeiserX/n8n-nodes-way-cms) | n8n community node for Way-CMS archived web content management | +| [n8n-nodes-way-cms](https://github.com/GeiserX/n8n-nodes-way-cms) (archived) | n8n community node for Way-CMS archived web content management | diff --git a/docs/usage.md b/docs/usage.md index 33150fb..c61d372 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -52,7 +52,7 @@ wayback-diff url1 url2 --format unified ```bash # Crawl and compare across linked pages (depth-limited) -wayback-diff url1 url2 --traverse --depth 2 +wayback-diff url1 url2 --traverse --max-depth 2 ``` ## Advanced options @@ -142,3 +142,64 @@ Structured output for programmatic processing: ### Unified diff Standard unified diff format, compatible with `patch` and code review tools. + +## CI/CD integration + +Wayback-Diff returns meaningful exit codes designed for pipeline gates: + +| Exit Code | Meaning | +|-----------|---------| +| `0` | No differences detected | +| `1` | Low or medium significance changes | +| `2` | High significance changes detected | + +### GitHub Actions example + +```yaml +name: Visual Regression Check +on: + pull_request: + +jobs: + diff: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Install Wayback-Diff + run: | + pip install "wayback-diff[visual]" + + - name: Compare staging vs production + run: | + wayback-diff \ + https://staging.example.com \ + https://production.example.com \ + --visual --markdown --format json -o diff.json + + - name: Upload report + if: always() + uses: actions/upload-artifact@v4 + with: + name: diff-report + path: reports/ +``` + +### Shell script gate + +```bash +wayback-diff "$OLD_URL" "$NEW_URL" --format json -o result.json +EXIT_CODE=$? + +if [ $EXIT_CODE -eq 2 ]; then + echo "BLOCKING: high-significance changes detected" + exit 1 +elif [ $EXIT_CODE -eq 1 ]; then + echo "WARNING: minor changes detected" +fi +``` diff --git a/setup.py b/setup.py index 6b951f9..2b3c6b9 100644 --- a/setup.py +++ b/setup.py @@ -10,12 +10,12 @@ version="1.1.0", author="geiserx", author_email="sergio@geiser.cloud", - description="A comprehensive tool for comparing web pages with Wayback Machine support", + description="Compare web pages, with Wayback Machine artifact cleaning and significance scoring", long_description=long_description, long_description_content_type="text/markdown", url="https://github.com/GeiserX/Wayback-Diff", - license="GPL-3.0-only", - license_files=[], + license="GPL-3.0-or-later", + license_files=["LICENSE"], packages=find_packages(), classifiers=[ "Development Status :: 3 - Alpha", From 068f4076428eb7fcded90436d5331d1d0c804608 Mon Sep 17 00:00:00 2001 From: GeiserX <9169332+GeiserX@users.noreply.github.com> Date: Tue, 29 Sep 2026 23:33:12 +0200 Subject: [PATCH 2/2] docs: quote the visual extra so zsh does not glob it --- docs/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 55d859b..ea781c7 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -8,7 +8,7 @@ Wayback-Diff needs Python 3.10 or newer. pip install wayback-diff # With visual comparison support -pip install wayback-diff[visual] +pip install "wayback-diff[visual]" ``` ## From source