feat: v0.5.0 — comprehensive documentation release
Theme: documentation and project polish. No public-API changes; this is the v0.5 release that elevates heuropt's docs/onboarding/governance to bar-setting status. Adds: - mdbook user guide at docs/book/ with intro, getting-started, defining-problems, choosing-an-algorithm, cookbook (7 recipes), comparison vs other libraries, stability/SemVer, migration guides. Deploys to https://swaits.github.io/heuropt/ via .github/workflows/ docs.yml. - Runnable rustdoc examples on every algorithm (35 of them), all exercised by cargo test --doc. - Three real-world examples: portfolio.rs (multi-obj with budget constraint), hyperparam_tuning.rs (BO + TPE), scheduling.rs (permutation via SA + SwapMutation against Smith's-rule oracle). - Governance: CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md (adopting builderscode.org's Builder's Code of Conduct), GitHub issue templates, PR template. Polishes: - README hero with badges + user-guide link. - lib.rs crate-level docs. - CHANGELOG entry for 0.5.0. Bumps Cargo.toml to 0.5.0.
This commit is contained in:
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: Bug report
|
||||
about: A correctness, performance, or panic bug in heuropt
|
||||
title: "bug: <one-line summary>"
|
||||
labels: bug
|
||||
---
|
||||
|
||||
## What happened
|
||||
|
||||
<Concise description of the bug.>
|
||||
|
||||
## Reproducer
|
||||
|
||||
```rust
|
||||
// Smallest example that demonstrates the bug. Ideally <30 lines and
|
||||
// runnable as a fresh `examples/repro.rs`. Include the Cargo.toml
|
||||
// `[features]` you used.
|
||||
```
|
||||
|
||||
Command used:
|
||||
|
||||
```sh
|
||||
cargo run --release --example repro
|
||||
```
|
||||
|
||||
## Expected vs observed
|
||||
|
||||
- **Expected:** <what should happen>
|
||||
- **Observed:** <what actually happens>
|
||||
|
||||
## Environment
|
||||
|
||||
- heuropt version:
|
||||
- `rustc --version`:
|
||||
- OS / arch:
|
||||
- Feature flags enabled:
|
||||
|
||||
## Additional context
|
||||
|
||||
<Anything else — fuzz artifact path, screenshots, profiler output.>
|
||||
@@ -0,0 +1,8 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: Security vulnerability
|
||||
url: https://github.com/swaits/heuropt/security/advisories/new
|
||||
about: Please use private vulnerability reporting — do not open a public issue. See SECURITY.md.
|
||||
- name: Question / discussion
|
||||
url: https://github.com/swaits/heuropt/discussions
|
||||
about: For open-ended questions or design discussions.
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
name: Docs issue
|
||||
about: Something in the README, mdbook guide, or rustdoc is wrong, missing, or unclear
|
||||
title: "docs: <one-line summary>"
|
||||
labels: documentation
|
||||
---
|
||||
|
||||
## Where
|
||||
|
||||
- [ ] `README.md`
|
||||
- [ ] mdbook user guide (chapter / section: ____ )
|
||||
- [ ] rustdoc on a specific item (path: ____ )
|
||||
- [ ] Examples (`examples/____.rs`)
|
||||
- [ ] CHANGELOG / migration guide
|
||||
- [ ] Other: ____
|
||||
|
||||
## What's wrong
|
||||
|
||||
<Concrete description: typo, broken link, outdated code sample,
|
||||
missing topic, unclear explanation, etc.>
|
||||
|
||||
## What it should say (if you know)
|
||||
|
||||
<Optional: proposed wording or correct content. Even a sketch helps.>
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: Feature request
|
||||
about: Propose a new algorithm, operator, metric, or API addition
|
||||
title: "feat: <one-line summary>"
|
||||
labels: enhancement
|
||||
---
|
||||
|
||||
## What and why
|
||||
|
||||
<What you want, and the problem it solves. If this is a new algorithm
|
||||
or operator, cite the paper or canonical reference.>
|
||||
|
||||
## Proposed API sketch
|
||||
|
||||
```rust
|
||||
// What the public surface would look like — config struct fields,
|
||||
// trait impl, etc. Doesn't need to be final, just enough to discuss.
|
||||
```
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
<Other approaches you thought about and why this one wins. If a
|
||||
similar feature already exists in heuropt or another Rust crate,
|
||||
explain how this differs.>
|
||||
|
||||
## Scope
|
||||
|
||||
- [ ] New trait (will need API discussion)
|
||||
- [ ] New algorithm
|
||||
- [ ] New operator
|
||||
- [ ] New metric / Pareto utility
|
||||
- [ ] New optional feature flag
|
||||
- [ ] Change to existing public API (potentially breaking)
|
||||
|
||||
## Willing to implement?
|
||||
|
||||
- [ ] Yes, I'll send a PR.
|
||||
- [ ] Yes, but I'd like guidance on the design first.
|
||||
- [ ] No, I'm reporting the need.
|
||||
@@ -0,0 +1,32 @@
|
||||
<!--
|
||||
Thanks for the contribution! Please skim CONTRIBUTING.md if you
|
||||
haven't yet — it has the local-test checklist and the conventional-
|
||||
commits requirement.
|
||||
-->
|
||||
|
||||
## What
|
||||
|
||||
<One- or two-sentence summary. Focus on the *what* and *why*, not
|
||||
the *how*.>
|
||||
|
||||
## Why
|
||||
|
||||
<Motivation. Link the issue this resolves with `Closes #N` if
|
||||
applicable.>
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] `cargo fmt --all`
|
||||
- [ ] `cargo clippy --all-targets --all-features -- -D warnings`
|
||||
- [ ] `cargo test` and `cargo test --all-features`
|
||||
- [ ] `cargo doc --no-deps --all-features` (with `-D warnings`)
|
||||
- [ ] Conventional-commit subject(s) (`<type>(<scope>): <summary>`)
|
||||
- [ ] If touching algorithm output: confirmed bit-identical results
|
||||
via `cargo run --release --example compare`
|
||||
- [ ] If perf change: included gungraun before/after numbers in the
|
||||
commit message
|
||||
- [ ] Updated CHANGELOG.md under `[Unreleased]` if user-visible
|
||||
|
||||
## Anything else
|
||||
|
||||
<Caveats, follow-ups, screenshots, perf numbers, etc.>
|
||||
@@ -0,0 +1,48 @@
|
||||
name: Docs
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
tags: ["v*.*.*"]
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: pages
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
build:
|
||||
name: Build mdbook
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Install mdbook
|
||||
run: |
|
||||
mkdir -p ~/.local/bin
|
||||
curl -sSL "https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-musl.tar.gz" \
|
||||
| tar -xz -C ~/.local/bin
|
||||
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
|
||||
- name: Build
|
||||
run: |
|
||||
cd docs/book
|
||||
mdbook build
|
||||
- uses: actions/configure-pages@v5
|
||||
- uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: target/book
|
||||
|
||||
deploy:
|
||||
name: Deploy to GitHub Pages
|
||||
needs: build
|
||||
runs-on: ubuntu-latest
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
steps:
|
||||
- id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
Reference in New Issue
Block a user