Maintenance and reproducibility

Written by Elena David, SEO, ORM, and AI Visibility Consultant.

Preserve a reproducible run

A report alone does not contain its input paths or complete command. Preserve these elements together when a run must be reproducible:

• previous snapshot;
• current snapshot;
• exact CLI command;
• application version or source revision;
• Python version;
• alerts.csv;
• monitoring_report.html;
• terminal output and validation warnings.

Use a unique output directory:

reputation-monitor \
  --previous data/reviews_previous.csv \
  --current data/reviews_current.csv \
  --maximum-rating 2 \
  --output-dir reports/2026-10-17-example

The program creates the directory but does not write a manifest. Record the command separately.

Update synthetic test data

1. Keep all practices, people, review text, and source labels fictional.
2. Preserve the exact seven-column header.
3. Retain stable IDs for records that represent the same review.
4. Add new IDs only to the current snapshot when demonstrating detection.
5. Decide whether malformed rows are intentional validation fixtures.
6. Run the CLI and compare all counts with the intended scenario.
7. Update tests and documentation when expected outputs change.

Do not insert real patient or health information.

Verify generated reports

After updating inputs:

1. Confirm warnings match intentional invalid rows.
2. Count data rows in alerts.csv.
3. Confirm each alert ID is new.
4. Confirm each alert rating is at or below the selected maximum alert rating.
5. Open the HTML report and compare its four metrics with the terminal.
6. Confirm HTML special characters render as text.
7. Retain separate run directories if previous outputs matter.

Run regression tests

python -m pytest

Run the complete suite after any source, packaging, or test-fixture change. Add a focused regression test when correcting a defect. Do not infer a coverage percentage from the number of passing tests.

Maintain code-documentation alignment

Review the affected documentation whenever any of these change:

Use DOCUMENTATION_MAINTENANCE.md for the editorial review workflow.

Versioning

Application version and documentation version are separate. Update the documentation version when published content changes, even if application behavior does not. Record reviewed application versions so readers can identify drift.