Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
121 lines (93 loc) · 5.09 KB

CONTRIBUTING.md

File metadata and controls

121 lines (93 loc) · 5.09 KB
Raw

Contributing

Thanks for helping. GreenBubbles handles very private data in formats WeChat doesn't document and often changes. A good contribution makes the tool easier to understand, easier to check, or more careful. It is fine, and often better, for a change to make the tool refuse to do something.

Contributions are accepted under the MIT License. By submitting one, you agree it can be shared under that license and confirm you have the right to submit it. Don't submit code copied from another project, or anything you aren't sure can be shared.

Security reports never go in an issue. Follow SECURITY.md.

The most useful thing you can report

A kind of message, table, or attachment that GreenBubbles reads wrong or only partly. Keeping up with WeChat's changing formats never ends, and a clear description of something GreenBubbles gets wrong is worth more than almost any code change.

Describe its structure, not its content: type codes, table layouts, column names, counts, and what GreenBubbles showed versus what it should have shown. Include no message text, no IDs, and no full file paths.

Before opening an issue

  • Search existing issues and the roadmap.
  • Check known limitations and the FAQ; it may already be documented.
  • Remove every message, name, account ID, database key, file path, photo or file, and any hash made from a private file.
  • For a format problem, describe the structure or build a small made-up example.
  • Include the GreenBubbles commit or version, macOS version, Mac chip, WeChat version, the command you ran, what you expected, and what happened.
  • Say whether you were reading live WeChat data, a backup, or made-up test data. Don't upload the data itself.

Most commands can print a JSON report with no personal content, so you have something safe to paste. swift scripts/check-live-database.swift prints one that covers the whole reading process.

Development setup

You need macOS 14 or later, Swift 6, and Rust with Cargo. From the repository root:

git config core.hooksPath scripts/git-hooks

swift format lint --strict --recursive Package.swift Sources Tests
swift test
swift build -c release

swift scripts/check-distribution-inventory.swift
swift scripts/check-secret-hygiene.swift
swift scripts/check-pinned-build-profile.swift

cd Native/GreenBubbles
cargo fmt --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked --all-targets
cargo install cargo-audit --locked --version 0.22.2
cargo audit --file Cargo.lock

The first line turns on a check that stops you from committing secrets; run it once per clone. The rest are the formatting, test, and safety checks CI runs. If this list and CI ever disagree, CI is right.

Test data: made-up only

Test data (fixtures) in this repository must be made up, generated by a script, or clearly free to share. Never commit:

  • real SQLite/WCDB pages, WAL frames, schemas copied from a real database, or database fragments;
  • messages, contact data, media, Moments data, account identifiers, local paths, or stable digests of any of those;
  • keys, passphrases, recovery words, signing seeds, cookies, session material, logs, crash reports, or memory captures;
  • proprietary application binaries, extracted resources, disassembly, or decompiled source;
  • a "sanitized" artefact, unless how it was generated and why it is redistributable are both documented.

Prefer a script that generates test data and makes the interesting structure obvious over a file that just happens to work. Test both the case that should work and the nearby cases that should be refused; in this project, refusing safely is usually the point.

Changes that affect privacy or safety

If a change touches privacy, permissions, key capture, the AI connector (the part that decides what an AI may read), or sending messages, the pull request should explain:

  1. what the user is trying to do, and exactly which data or actions the change covers;
  2. what is trusted, and which inputs an attacker could control;
  3. the limits, permission checks, and what happens when something fails;
  4. what is logged, saved, or revealed, and what is deliberately left out;
  5. how users can still see where data came from, how recent it is, and what is missing;
  6. made-up tests for tampering, unclear input, retries, and unsafe paths;
  7. any new dependency, license, platform, or packaging effect.

One rule matters most. Never let a change quietly turn reading into key capture, a query into a bulk export, or a draft into an action that sends something. Those three limits are the product. Loosening one needs its own deliberate change and review, never a side effect of cleanup.

Pull requests

Keep each one focused, and start with what users will notice. Include:

  • the problem and how you solved it;
  • the effect on safety and privacy;
  • the tests you ran, and anything you chose not to test;
  • documentation updates for any changed command, format, or limit;
  • any new or changed dependency or license notice.

Please also follow the Code of Conduct.