github/himalaya
1
0
Fork 0
mirror of https://github.com/pimalaya/himalaya.git synced 2026-06-15 11:27:53 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update contributing and security

Browse Source
This commit is contained in:
Clément DOUIN
2026-05-20 02:21:55 +02:00
parent 44eff37470
commit dabfb20431
2 changed files with 85 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+72 -35
View File
@@ -1,69 +1,106 @@
# Contributing guide
Thank you for investing your time in contributing to Himalaya CLI!
Thank you for investing your time in contributing to Himalaya CLI.
## Development
## Development environment
The development environment is managed by [Nix](https://nixos.org/download.html).
Running `nix-shell` will spawn a shell with everything you need to get started with the lib.
The development environment is managed by [Nix flakes](https://nixos.wiki/wiki/Flakes). Running `nix develop` (or `nix-shell` for non-flake users) spawns a shell with the right Rust toolchain, `cargo-deny`, `pkg-config` and the OpenSSL / DBus libraries.
If you do not want to use Nix, you can either use [rustup](https://rust-lang.github.io/rustup/index.html):
If you do not want to use Nix, install [rustup](https://rust-lang.github.io/rustup/index.html) and pull the toolchain pinned by `rust-version` in `Cargo.toml`:
```text
```
rustup update
```
or install manually the following dependencies:
- [cargo](https://doc.rust-lang.org/cargo/) (`v1.82`)
- [rustc](https://doc.rust-lang.org/stable/rustc/platform-support.html) (`v1.82`)
- `cargo` (>= `v1.87`)
- `rustc` (>= `v1.87`, edition 2024)
## Build
```text
```
cargo build
```
You can disable default [features](https://doc.rust-lang.org/cargo/reference/features.html) with `--no-default-features` and enable features with `--features feat1,feat2,feat3`.
You can disable default [features](https://doc.rust-lang.org/cargo/reference/features.html) with `--no-default-features` and enable individual features with `--features feat1,feat2`.
Finally, you can build a release with `--release`:
For example, an IMAP+SMTP-only release build:
```text
cargo build --no-default-features --features imap,smtp,keyring --release
```
cargo build --no-default-features --features imap,smtp,rustls-ring --release
```
The release profile (`[profile.release]` in `Cargo.toml`) sets `lto = "fat"`, `codegen-units = 1`, `strip = "symbols"` and `panic = "abort"` to keep the binary small.
## Project layout
Himalaya CLI is the command-line front-end of the [Pimalaya](https://github.com/pimalaya) project. Most of the work happens in companion crates rather than in this repository:
- [io-email](https://github.com/pimalaya/io-email): cross-protocol email client (`EmailClientStd`, shared `Envelope` / `Mailbox` / `Flag` / `Address` types, search DSL).
- [io-imap](https://github.com/pimalaya/io-imap), [io-jmap](https://github.com/pimalaya/io-jmap), [io-maildir](https://github.com/pimalaya/io-maildir), [io-smtp](https://github.com/pimalaya/io-smtp): per-protocol I/O-free coroutines plus the std-blocking clients that drive them.
- [io-http](https://github.com/pimalaya/io-http): I/O-free HTTP request/response state machines used by JMAP and the discovery wizard.
- [io-discovery](https://github.com/pimalaya/io-discovery): provider discovery (PACC, Thunderbird Autoconfiguration, RFC 6186 SRV) consumed by the wizard.
- [pimalaya/stream](https://github.com/pimalaya/stream): TCP / TLS / SASL plumbing shared by all std clients.
- [pimalaya/cli](https://github.com/pimalaya/cli): cross-binary CLI helpers (printer, prompt, wizard primitives, clap args, build-time env, spinner).
- [pimalaya/config](https://github.com/pimalaya/config): TOML configuration loader and shell-expanded secrets.
- [pimalaya/mml](https://github.com/pimalaya/mml): MIME Meta Language composer / reader, plugged in via `[message.composer.*]` / `[message.reader.*]`.
- [pimalaya/sirup](https://github.com/pimalaya/sirup): session re-use over a Unix socket (pair with `imap.server` / `smtp.server` to amortize TLS handshakes).
- [pimalaya/ortie](https://github.com/pimalaya/ortie): standalone OAuth 2.0 token broker (replaces v1's bundled `oauth-lib`).
- [pimalaya/mimosa](https://github.com/pimalaya/mimosa): standalone secret manager (replaces v1's bundled `keyring-lib`).
Bugs touching protocol semantics usually live in the matching `io-*` crate; rendering, composition and CLI surface live here.
## Override dependencies
If you want to build Himalaya CLI with a dependency installed locally (for example `email-lib`), then you can [override it](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html) by adding the following lines at the end of `Cargo.toml`:
`Cargo.toml` already patches every Pimalaya crate to its git remote so the working copy compiles against the latest `master` of each lib:
```toml
[patch.crates-io]
email-lib = { path = "/path/to/email-lib" }
io-discovery.git = "https://github.com/pimalaya/io-discovery"
io-email.git = "https://github.com/pimalaya/io-email"
io-http.git = "https://github.com/pimalaya/io-http"
io-imap.git = "https://github.com/pimalaya/io-imap"
io-jmap.git = "https://github.com/pimalaya/io-jmap"
io-maildir.git = "https://github.com/pimalaya/io-maildir"
io-smtp.git = "https://github.com/pimalaya/io-smtp"
pimalaya-cli.git = "https://github.com/pimalaya/cli"
pimalaya-config.git = "https://github.com/pimalaya/config"
pimalaya-stream.git = "https://github.com/pimalaya/stream"
```
If you get the following error:
```text
note: perhaps two different versions of crate email are being used?
```
then you may need to override more Pimalaya's sub-dependencies:
To build against a local checkout of one of those crates, swap the matching `.git = "..."` for `.path = "../<repo>"`. For example, with `io-email` next to `himalaya`:
```toml
[patch.crates-io]
email-lib.path = "/path/to/core/email"
imap-client.path = "/path/to/imap-client"
keyring-lib.path = "/path/to/core/keyring"
mml-lib.path = "/path/to/core/mml"
oauth-lib.path = "/path/to/core/oauth"
pgp-lib.path = "/path/to/core/pgp"
pimalaya-tui.path = "/path/to/tui"
process-lib.path = "/path/to/core/process"
secret-lib.path = "/path/to/core/secret"
io-email.path = "../io-email"
```
*See [pimalaya/core#32](https://github.com/pimalaya/core/issues/32) for more information.*
If cargo complains about *"perhaps two different versions of crate X are being used"*, patch every Pimalaya crate that pulls X transitively so the dep graph converges on the local copies:
```toml
[patch.crates-io]
io-discovery.path = "../io-discovery"
io-email.path = "../io-email"
io-http.path = "../io-http"
io-imap.path = "../io-imap"
io-jmap.path = "../io-jmap"
io-maildir.path = "../io-maildir"
io-smtp.path = "../io-smtp"
pimalaya-cli.path = "../cli"
pimalaya-config.path = "../config"
pimalaya-stream.path = "../stream"
```
## Lint, test, audit
```
cargo fmt
cargo clippy --all-features --all-targets
cargo test --all-features
cargo deny check
```
`cargo deny` runs against the rules in [`deny.toml`](./deny.toml) (license allow-list and allowed git sources).
## Commit style
Starting from the `v1.0.0`, Himalaya CLI tries to adopt the [conventional commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary).
Himalaya CLI follows the [conventional commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary). Prefix every commit with one of `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `ci`, `build`, optionally scoped (`fix(imap): ...`).
SECURITY.md
+13
View File
@@ -0,0 +1,13 @@
# Security Policy
## Supported Versions
| Version | Supported |
| ------- | -------------- |
| 2.x.x | :green_circle: |
| 1.x.x | :red_circle: |
| 0.x.x | :red_circle: |
## Reporting a Vulnerability
https://github.com/pimalaya/himalaya/issues