Skip to content

Commit 275d04d

Browse files
author
Yuma Ichikawa
committed
ci: add issue/PR templates, docs deploy, coverage and release-drafter
Round out the OSS-hygiene story for QQA4CO so the project no longer leans on tribal knowledge to maintain. - .github/ISSUE_TEMPLATE/{bug_report,feature_request,config}.yml plus .github/PULL_REQUEST_TEMPLATE.md push GitHub's community-profile health from 85% to 100% and steer reporters toward Discussions / the security advisory flow. - .github/workflows/docs.yml builds the MkDocs Material site on every push to main (or docs/ change) and deploys it via the github-pages environment, so `https://yuma-ichikawa.github.io/QQA4CO/` becomes the canonical documentation URL once the user enables Pages. - .github/workflows/release-drafter.yml + release-drafter.yml keep a draft release rolling on main, auto-categorising PRs by Conventional Commit prefix so future tags only need a one-click publish. - ci.yml now runs pytest with --cov=src/qqa --cov-report=xml and uploads to Codecov on the 3.11 matrix entry; pytest-cov is added to the dev dependency group and coverage.xml is git-ignored. - README.md gets two new badges (Documentation, GitHub Discussions) to advertise the new entry points. Made-with: Cursor
1 parent 697d5f8 commit 275d04d

12 files changed

Lines changed: 414 additions & 2 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
name: Bug report
2+
description: Report a reproducible bug in QQA4CO.
3+
title: "[Bug]: "
4+
labels: ["bug", "needs-triage"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for taking the time to file a bug report. Please fill in
10+
the sections below — runnable reproduction code is the single
11+
most useful thing you can give us.
12+
- type: textarea
13+
id: summary
14+
attributes:
15+
label: Short description
16+
description: One or two sentences describing what went wrong.
17+
placeholder: "qqa.anneal returns NaN best_obj when ..."
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: repro
22+
attributes:
23+
label: Minimal reproduction
24+
description: |
25+
A self-contained snippet that reproduces the issue. Prefer
26+
synthetic graphs over private data.
27+
render: python
28+
placeholder: |
29+
import networkx as nx, qqa
30+
g = nx.random_regular_graph(d=3, n=64, seed=0)
31+
prob = qqa.MaximumIndependentSet(g, device="cpu")
32+
res = qqa.anneal(prob, sol_size=8, num_epochs=100,
33+
min_bg=-2.0, max_bg=0.1, device="cpu")
34+
print(res.best_obj)
35+
validations:
36+
required: true
37+
- type: textarea
38+
id: actual
39+
attributes:
40+
label: Actual behaviour
41+
description: Full stack trace or unexpected output.
42+
render: shell
43+
validations:
44+
required: true
45+
- type: textarea
46+
id: expected
47+
attributes:
48+
label: Expected behaviour
49+
description: What did you expect to happen instead?
50+
validations:
51+
required: true
52+
- type: input
53+
id: qqa_version
54+
attributes:
55+
label: qqa version
56+
description: "Output of: python -c 'import qqa; print(qqa.__version__)'"
57+
placeholder: "0.4.0"
58+
validations:
59+
required: true
60+
- type: input
61+
id: torch_version
62+
attributes:
63+
label: torch version
64+
placeholder: "2.4.1+cpu"
65+
validations:
66+
required: true
67+
- type: input
68+
id: python_version
69+
attributes:
70+
label: Python version
71+
placeholder: "3.11.9"
72+
validations:
73+
required: true
74+
- type: dropdown
75+
id: device
76+
attributes:
77+
label: Device
78+
options:
79+
- "CPU"
80+
- "CUDA (NVIDIA)"
81+
- "MPS (Apple Silicon)"
82+
- "Other / not sure"
83+
validations:
84+
required: true
85+
- type: input
86+
id: os
87+
attributes:
88+
label: Operating system
89+
placeholder: "Ubuntu 22.04 / macOS 14.5 / Windows 11"
90+
validations:
91+
required: true
92+
- type: textarea
93+
id: extra
94+
attributes:
95+
label: Additional context
96+
description: Anything else worth knowing — recent changes, related issues, screenshots.

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Question / discussion
4+
url: https://github.com/Yuma-Ichikawa/QQA4CO/discussions
5+
about: |
6+
For usage questions, ideas, and "is this the right tool for X?"
7+
please open a discussion instead of an issue.
8+
- name: Security advisory
9+
url: https://github.com/Yuma-Ichikawa/QQA4CO/security/advisories/new
10+
about: |
11+
Privately report security vulnerabilities. See SECURITY.md for
12+
the full disclosure policy.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Feature request
2+
description: Suggest a new feature, problem class, or solver enhancement.
3+
title: "[Feature]: "
4+
labels: ["enhancement", "needs-triage"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for proposing a new feature. The clearer you can describe
10+
the use case the better — it helps us decide between adding the
11+
feature, exposing an extension point, or pointing you to an
12+
existing knob.
13+
- type: textarea
14+
id: problem
15+
attributes:
16+
label: Problem statement
17+
description: What can you not do today, or what is awkward to do?
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: proposal
22+
attributes:
23+
label: Proposed solution
24+
description: |
25+
How would the API / CLI / dashboard look? Concrete signatures
26+
or screenshots are very welcome.
27+
render: python
28+
validations:
29+
required: true
30+
- type: textarea
31+
id: alternatives
32+
attributes:
33+
label: Alternatives considered
34+
description: Workarounds you tried, related libraries, prior art.
35+
- type: dropdown
36+
id: scope
37+
attributes:
38+
label: Which part of the project does this touch?
39+
multiple: true
40+
options:
41+
- "QQA solver (qqa.anneal / annealing.py)"
42+
- "Simulated Annealing (qqa.simulated_annealing / sa.py)"
43+
- "PI-GNN / CPRA trainers (qqa.pignn)"
44+
- "Problem catalogue (qqa.problems.*)"
45+
- "CLI (qqa.cli)"
46+
- "Streamlit dashboard (app/)"
47+
- "Documentation (docs/)"
48+
- "Build / packaging / CI"
49+
- "Other"
50+
validations:
51+
required: true
52+
- type: textarea
53+
id: extra
54+
attributes:
55+
label: Additional context

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<!--
2+
Thanks for contributing to QQA4CO! Please fill in the sections below
3+
so reviewers can land your change quickly.
4+
-->
5+
6+
## Summary
7+
8+
<!-- 1-3 sentences: what does this PR change and why? -->
9+
10+
## Type of change
11+
12+
- [ ] Bug fix (non-breaking change which fixes an issue)
13+
- [ ] New feature (non-breaking change which adds functionality)
14+
- [ ] Breaking change (fix or feature that would cause existing behaviour to change)
15+
- [ ] Documentation only
16+
- [ ] Build / CI / tooling
17+
18+
## Checklist
19+
20+
- [ ] I ran `uv run ruff check src tests scripts app` and it is clean.
21+
- [ ] I ran `uv run ruff format src tests scripts app` (or `pre-commit run --all-files`).
22+
- [ ] I ran `uv run pytest -q` and all tests pass locally.
23+
- [ ] If I touched solver behaviour, I added or updated a regression
24+
test under `tests/`.
25+
- [ ] If I changed a user-visible API, I updated `docs/` and the
26+
relevant Quickstart / How-to entries.
27+
- [ ] I updated `CHANGELOG.md` under `## [Unreleased]`.
28+
- [ ] If I added a new dependency, I justified it in the PR description.
29+
30+
## Related issue / discussion
31+
32+
<!-- Closes #..., refs #..., or "n/a" -->
33+
34+
## Reproduction or benchmark
35+
36+
<!--
37+
For perf or numerical changes, paste before/after numbers (best_obj,
38+
runtime, GPU memory). For UI changes, attach a screenshot or a short
39+
recording of the dashboard.
40+
-->

‎.github/release-drafter.yml‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
name-template: "v$RESOLVED_VERSION"
2+
tag-template: "v$RESOLVED_VERSION"
3+
template: |
4+
## What's changed
5+
6+
$CHANGES
7+
8+
## Install
9+
10+
```bash
11+
pip install qqa==$RESOLVED_VERSION
12+
pip install "qqa[gui]==$RESOLVED_VERSION"
13+
```
14+
15+
**Full changelog**: https://github.com/Yuma-Ichikawa/QQA4CO/compare/$PREVIOUS_TAG...v$RESOLVED_VERSION
16+
17+
categories:
18+
- title: "Features"
19+
labels:
20+
- "enhancement"
21+
- "feature"
22+
- title: "Bug fixes"
23+
labels:
24+
- "bug"
25+
- "fix"
26+
- title: "Performance"
27+
labels:
28+
- "performance"
29+
- title: "Documentation"
30+
labels:
31+
- "documentation"
32+
- "docs"
33+
- title: "Build & CI"
34+
labels:
35+
- "ci"
36+
- "build"
37+
- "dependencies"
38+
- title: "Refactoring"
39+
labels:
40+
- "refactor"
41+
- "chore"
42+
43+
change-template: "- $TITLE (#$NUMBER) by @$AUTHOR"
44+
change-title-escapes: '\<*_&'
45+
46+
version-resolver:
47+
major:
48+
labels:
49+
- "major"
50+
- "breaking"
51+
minor:
52+
labels:
53+
- "minor"
54+
- "enhancement"
55+
- "feature"
56+
patch:
57+
labels:
58+
- "patch"
59+
- "bug"
60+
- "fix"
61+
- "chore"
62+
- "docs"
63+
default: patch
64+
65+
autolabeler:
66+
- label: "feature"
67+
title:
68+
- '/^feat(\(.*\))?:/i'
69+
- label: "bug"
70+
title:
71+
- '/^fix(\(.*\))?:/i'
72+
- label: "documentation"
73+
title:
74+
- '/^docs(\(.*\))?:/i'
75+
- label: "performance"
76+
title:
77+
- '/^perf(\(.*\))?:/i'
78+
- label: "refactor"
79+
title:
80+
- '/^refactor(\(.*\))?:/i'
81+
- label: "chore"
82+
title:
83+
- '/^chore(\(.*\))?:/i'
84+
- '/^style(\(.*\))?:/i'
85+
- label: "ci"
86+
title:
87+
- '/^ci(\(.*\))?:/i'
88+
- label: "build"
89+
title:
90+
- '/^build(\(.*\))?:/i'
91+
- label: "dependencies"
92+
title:
93+
- '/^deps(\(.*\))?:/i'
94+
95+
exclude-labels:
96+
- "skip-changelog"
97+
- "duplicate"
98+
- "invalid"
99+
- "wontfix"

‎.github/workflows/ci.yml‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,17 @@ jobs:
3939
- name: Ruff format check
4040
run: uv run ruff format --check src tests scripts app
4141

42-
- name: Run tests
43-
run: uv run pytest -q
42+
- name: Run tests with coverage
43+
run: uv run pytest -q --cov=src/qqa --cov-report=xml --cov-report=term
44+
45+
- name: Upload coverage to Codecov
46+
if: matrix.python-version == '3.11'
47+
uses: codecov/codecov-action@v4
48+
with:
49+
files: ./coverage.xml
50+
flags: unittests
51+
fail_ci_if_error: false
52+
token: ${{ secrets.CODECOV_TOKEN }}
4453

4554
- name: MkDocs strict build
4655
run: uv run mkdocs build --clean --strict

‎.github/workflows/docs.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Deploy docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "docs/**"
8+
- "mkdocs.yml"
9+
- "src/**"
10+
- ".github/workflows/docs.yml"
11+
workflow_dispatch:
12+
13+
# Required so the workflow can publish to the GitHub Pages environment
14+
# managed automatically by `actions/deploy-pages`.
15+
permissions:
16+
contents: read
17+
pages: write
18+
id-token: write
19+
20+
# Avoid clobbering each other when several pushes land back-to-back.
21+
concurrency:
22+
group: "pages"
23+
cancel-in-progress: true
24+
25+
jobs:
26+
build:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- uses: actions/checkout@v5
30+
- uses: astral-sh/setup-uv@v8.1.0
31+
with:
32+
enable-cache: true
33+
- name: Set up Python
34+
run: uv python install 3.11
35+
- name: Install with docs extras (CPU torch)
36+
env:
37+
PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
38+
run: uv sync --extra docs
39+
- name: Build site
40+
run: uv run mkdocs build --clean --strict --site-dir _site
41+
- uses: actions/upload-pages-artifact@v3
42+
with:
43+
path: _site
44+
45+
deploy:
46+
needs: build
47+
runs-on: ubuntu-latest
48+
environment:
49+
name: github-pages
50+
url: ${{ steps.deployment.outputs.page_url }}
51+
steps:
52+
- id: deployment
53+
uses: actions/deploy-pages@v4

0 commit comments

Comments
 (0)