Project Hope 1.8.0 — Bring your contacts 🌱

After a long time building, testing, rebuilding, and caring about the small details, I am proud to release Project Hope 1.8.0. This release makes one of the hardest parts of changing charity software feel calm: bringing your contacts with you.

Choose. Review. Finish. Nothing changes until the charity approves it.

Project Hope 1.8 turns one of the most stressful parts of changing software into a guided, reversible workflow. A charity owner can bring a normal Excel or CSV contact list into the CRM, see every error and possible match before anything changes, correct the source file, import only reviewed rows, and export the data again without needing a developer.

Licensing notice: this public repository still does not include an approved software license. Source visibility does not grant reuse or redistribution rights; the planned Community terms remain an owner decision.

A migration flow made for nontechnical teams

• CRM now has dedicated Contacts, Import & export, and Find duplicates views in the browser and desktop app.
• Owners and administrators can download a polished Excel template with instructions, recognized values, filters, frozen headings, and dropdown validation; a simple CSV template is also available.
• XLSX, CSV, and TSV contact lists can be previewed in three steps: choose, review, finish.
• Every row is labelled Ready to add, Existing match, Possible duplicate, or Needs correction, with plain-language reasons and an explicit action.
• New rows default to creation. Matches and possible duplicates default to skip. Invalid rows cannot be imported.
• A reviewer can fill missing details on a selected match without overwriting an existing name, email, phone, or reference. Notes append, while stricter sensitivity and consent states win.
• The completion view reports exactly how many contacts were created, filled in, already complete, skipped, or invalid.
• Coordinators and staff can correct individual contacts. Viewer accounts remain read-only and do not see mutation or bulk-data controls.

The plain-language contact migration guide explains the complete charity journey and troubleshooting path.

Duplicate cleanup without deleting history

• Deterministic matching explains exact email/reference, strong name-and-phone, and possible full-name/organization matches.
• The reviewer compares both records, chooses which contact remains active, and must explicitly confirm the pair.
• A merge fills blank details, combines notes, preserves the stricter sensitivity and consent state, and moves linked households, interactions, consent, schedules, waitlist entries, email links, donor snapshots, volunteer profiles, and relationships.
• The duplicate becomes a preserved source record pointing to the active contact; it is not hard-deleted.
• Legal holds block merging. Two volunteer profiles also block the merge so a person can resolve that conflict safely.

Spreadsheet and tenant safeguards

• Import defaults are bounded to 5 MB, 2,500 contact rows, and 50 columns; production operators can set approved limits.
• Modern XLSX archives are checked for unsafe paths, excessive members or expansion, dangerous compression ratios, macros, and external workbook links.
• Spreadsheet formulas are rejected at row level and must be replaced by a reviewed text value.
• CSV exports neutralize formula-leading text. Excel exports force contact values to string cells.
• UTF-8 and Windows-1252 CSV input are supported, with explicit warnings when normalization occurs.
• Preview tokens expire after 15 minutes by default and are signed to the schema, user, organization, exact file digest, and row count.
• Commit reparses and revalidates the same upload inside a locked transaction. A changed file, user, organization, match, or expired preview fails closed.
• Project Hope does not persist a separate server-side copy of the preview spreadsheet. Migration audit events record counts, not contact rows or email addresses, and sensitive responses are private and non-cacheable.

Authorization correction

Generic organization record APIs now enforce the documented role boundary consistently: owner, administrator, coordinator, and staff roles can create or edit ordinary records; viewers can read but cannot POST or PATCH. Administrator-only resources and destructive actions retain their stricter controls.

Upgrade action

1. Back up the database and verify the approved restore path.
2. Deploy the core and web/desktop clients together.
3. Install the updated Python dependencies, including openpyxl and defusedxml.
4. Apply migration modules.0003_contact_merge_state.
5. Review PROJECT_HOPE_MAX_CRM_IMPORT_BYTES, PROJECT_HOPE_MAX_CRM_IMPORT_ROWS, and PROJECT_HOPE_CRM_IMPORT_PREVIEW_MAX_AGE_SECONDS; the supplied defaults are 5 MB, 2,500 rows, and 900 seconds.
6. Use synthetic contacts to download the template, preview an invalid/matched/new file, commit reviewed rows, export both formats, and complete one reversible duplicate rehearsal.
7. Read Move your contacts into Project Hope before handling real personal information.

Release verification

• 69 Django tests pass, including malformed and macro workbook rejection, formula handling, row limits, same-file duplicates, short-lived user/tenant/file binding, usable contact identity validation, viewer write denial, legal holds, merge conflicts, related-record reassignment, source preservation, and CSV/XLSX round-trips.
• 21 web and shared-client interaction journeys pass, including owner import, invalid-row correction cues, multipart safety, typed API-client upload/download behavior, contact editing, viewer-only presentation, explicit duplicate confirmation, and automated WCAG A/AA checks.
• Ruff, formatting, Mypy, migration drift, API-client types, OpenAPI parsing, the web production build, mobile type/security/export checks, desktop build, and development/production Compose validation pass.
• The 7-test AI gateway remains green; bounded adapters and human-review controls are unchanged.
• Production dependency audits report no known vulnerabilities for the Python services, web client, or desktop client. The documented mobile build-tool advisories remain covered by the locked parser patch and CI regression test in SECURITY.md.

Honest boundaries

Automated evidence does not replace a real charity migration. This release still needs a charity administrator to validate vocabulary, map a representative source spreadsheet, perform corrections, confirm a lossless export, and approve the resulting records before the original field exit condition can close.

Project Hope still does not provide a live managed deployment, billing, an approved software license, signed public installers, Apple/Google store publication, an independent penetration test, or external charity/accessibility acceptance. The generic macOS artifact is Apple silicon only. The verified Founding 10 count remains 0/10 until real applicants complete the production confirmation flow.