kingchenc
9309bf9d60
The documentation now lives in the wickra-lib/wickra-docs VitePress repo and
will deploy to docs.wickra.org. Rewrite every tracked, user-facing wiki link
in the main repo to the new canonical site:
- docs/README.md, CONTRIBUTING.md, PULL_REQUEST_TEMPLATE.md
- bindings/{node,python,wasm}/README.md, examples/wasm/README.md
- repo-metadata.toml: wiki_url/wiki_git -> docs_url/docs_git
Page paths map 1:1 to VitePress clean URLs (e.g. /wiki/Quickstart-Rust.md ->
docs.wickra.org/Quickstart-Rust). The sync-about.yml wiki-sync step is left
untouched on purpose: it stays until the docs site is live (tracked as P8.3).
The GitHub wiki itself is not deleted yet for the same reason.
117 lines
5.1 KiB
Markdown
117 lines
5.1 KiB
Markdown
# Contributing to Wickra
|
|
|
|
Thanks for your interest in improving Wickra. This document explains how to
|
|
build the project, the standards a change must meet, and how to get it merged.
|
|
|
|
## License of contributions
|
|
|
|
Wickra is licensed under the **PolyForm Noncommercial License 1.0.0** (see
|
|
[`LICENSE`](LICENSE)). By submitting a contribution you agree that it is
|
|
licensed to the project under those same terms. The Noncommercial license
|
|
permits use for any purpose **other than** a commercial one; keep that in mind
|
|
when proposing features or depending on Wickra elsewhere.
|
|
|
|
## Project layout
|
|
|
|
| Path | Contents |
|
|
| --- | --- |
|
|
| `crates/wickra-core` | The indicator engine — every indicator lives here. |
|
|
| `crates/wickra` | Thin umbrella crate re-exporting `wickra-core`. |
|
|
| `crates/wickra-data` | CSV reader, tick aggregator, resampler, Binance feed. |
|
|
| `bindings/python` | PyO3 bindings (`wickra` on PyPI). |
|
|
| `bindings/node` | napi-rs bindings (`wickra` on npm). |
|
|
| `bindings/wasm` | wasm-bindgen bindings (`wickra-wasm` on npm). |
|
|
| `examples/` | Runnable examples. |
|
|
| `docs/` | Pointer to the project Wiki, which holds all documentation. |
|
|
|
|
## Building and testing
|
|
|
|
### Rust
|
|
|
|
```bash
|
|
cargo fmt --all --check
|
|
cargo clippy --workspace --all-targets -- -D warnings
|
|
cargo test --workspace
|
|
cargo test -p wickra-data --features live-binance
|
|
```
|
|
|
|
The minimum supported Rust version is **1.86** for the workspace crates and
|
|
**1.88** for `bindings/node`; the `msrv` CI job enforces both. These floors are
|
|
not chosen freely — they are the lowest versions our dependencies allow
|
|
(criterion 0.8.2, the bench dev-dependency, requires 1.86; napi-build 2.3.2
|
|
requires 1.88). We keep the MSRV at that dependency-forced floor on purpose so
|
|
the library builds for the widest possible audience; please don't raise it
|
|
without a dependency that actually requires it.
|
|
|
|
### Python
|
|
|
|
```bash
|
|
cd bindings/python
|
|
python -m maturin build --release --out dist
|
|
python -m pip install --force-reinstall --no-deps dist/wickra-*.whl
|
|
python -m pytest -q
|
|
```
|
|
|
|
### Node
|
|
|
|
```bash
|
|
cd bindings/node
|
|
npm install
|
|
npx napi build --platform --release
|
|
node --test __tests__/
|
|
```
|
|
|
|
### WASM
|
|
|
|
```bash
|
|
wasm-pack build bindings/wasm --target web --release --features panic-hook
|
|
wasm-pack test --node bindings/wasm
|
|
```
|
|
|
|
## Lockfile policy
|
|
|
|
| Component | Lockfile | Tracked? | Why |
|
|
| --- | --- | --- | --- |
|
|
| Workspace (Rust) | `Cargo.lock` | **yes** | The workspace ships binaries (examples, fuzz harness) and CI builds, so the dependency graph is pinned for reproducible builds. |
|
|
| `bindings/node` | `package-lock.json` | **yes** | Reproducible `npm install` for the native binding. |
|
|
| `examples/node` | `package-lock.json` | **yes** | Same — the runnable Node examples link the binding via a `file:` dependency. |
|
|
| `bindings/python` | — | n/a (no lockfile) | PyO3 convention: the Python package has no Python runtime dependencies of its own, and its native code is already pinned through the workspace `Cargo.lock`. CI installs build/test tooling (`maturin`, `pytest`, `numpy`, `hypothesis`) directly via `pip`. |
|
|
| `fuzz` | `fuzz/Cargo.lock` | **no** (ignored) | `fuzz/` is a detached crate; `cargo-fuzz init` generates `fuzz/.gitignore` which ignores its `Cargo.lock`. The fuzz smoke job resolves dependencies fresh, so the lock is not needed for reproducibility here. |
|
|
| `site` (marketing) | `package-lock.json` | **no** (ghost-ignored) | The VitePress site is a local-only project excluded via `.git/info/exclude`; its lockfile stays local. |
|
|
|
|
When adding a new committed Node package, commit its `package-lock.json` too and
|
|
remove any matching ignore rule. Do **not** add a top-level `package-lock.json` —
|
|
the repository root is not an npm package.
|
|
|
|
## Standards for a change
|
|
|
|
- **Formatting & lints.** `cargo fmt` must leave the tree unchanged and
|
|
`cargo clippy ... -D warnings` must be clean. CI gates both.
|
|
- **Tests.** New behaviour needs tests; bug fixes need a regression test.
|
|
- **Indicator correctness.** A new or changed indicator must have a
|
|
reference-value test against a known-good source (TA-Lib, pandas-ta, or a
|
|
hand-computed value) and a `reset` test.
|
|
- **Streaming parity.** An indicator's `batch` output must equal the sequence
|
|
of `update` calls.
|
|
- **Bindings.** A change to a public indicator API must be mirrored across the
|
|
Python, Node, and WASM bindings, including their type stubs / `.d.ts`.
|
|
- **Docs.** Update the relevant page on the
|
|
[documentation site](https://docs.wickra.org) and the
|
|
`README.md` when behaviour or the public API changes. The docs live in
|
|
a separate git repository: `https://github.com/wickra-lib/wickra-docs`.
|
|
- **Changelog.** Add an entry under `## [Unreleased]` in `CHANGELOG.md`.
|
|
|
|
## Commit and pull-request workflow
|
|
|
|
1. Branch off `main`.
|
|
2. Keep commits focused — one logical change per commit, with an imperative
|
|
subject line and a body explaining *why*.
|
|
3. Open a pull request against `main` and fill in the template.
|
|
4. CI must be green before review.
|
|
|
|
## Reporting bugs and proposing features
|
|
|
|
Use the issue templates under
|
|
[`.github/ISSUE_TEMPLATE`](.github/ISSUE_TEMPLATE). For security-sensitive
|
|
reports, follow [`SECURITY.md`](SECURITY.md) instead of opening a public issue.
|