Skip to content

Commit 8c93a99

Browse files
StepenkoAnatoliStepenkoAnatoli
committed
docs: lead with the research preview and contributor guide
what changed: The README opens with an original accessible SVG workflow overview, followed by linked Shields badges for tests/CI, PolyForm Shield 1.0.0, last commit and stars. Added contributor setup, verification, issue-label and PR guidance, quick links and the requested closing star note. why: Make the repository easier to understand and contribute to from its first screen. The user requested a professional preview at the top, like SmartRouter's workflow graphic, plus useful badges and contribution documentation. The current Research-Kit name and research-first tagline remain the presentation identity; no behavior decision or alternative was set aside. what it touched: README.md, CONTRIBUTING.md, docs/assets/research-overview.svg and CHANGELOG.md. No declared code path changed, so no architecture-map or test-inventory change is owed. Existing GitHub Actions supply the CI status; the project is distributed as source and has no npm/PyPI download badge. what you verified: verified - SVG rendered and inspected at full and 830-pixel README width; its XML parses and its accessible labels and self-contained assets were checked. All 40 relative file links in README/CONTRIBUTING resolve. Every badge endpoint returned usable SVG, the workflow badge reported passing and the license label matches LICENSE. Preview is the first README block and the support note is the last. Handoff OK, preflight PASS (28 passing, one existing unstamped-brief warning), doctor READY collector/firecrawl-cli with existing deployment/edit-registration warnings, and git diff --check clean. A docs-only commit uses the normal commit gate; GitHub PR CI remains untested until publication. what you got wrong and fixed: mistake - the first preview badge label slightly clipped, the contribution draft guessed ADR-0117's filename, and the external-badge verifier assumed every SVG had a title. where - draft SVG badge, contribution freeze link and local verification helper. impact - visual clipping, one broken draft link, and a false refusal of Shields' valid stars SVG; no delivered change affected. cause - width and the exact slug were not checked before drafting, and the stars response shape was assumed. fix - widen the badge, adjust a long caption, use the actual ADR filename, and verify the stars response's linked label and numeric count; its README image has alt text. verified - the revised preview was inspected at README width, all local targets resolve and all four badge responses pass validation.
1 parent 3fa03fa commit 8c93a99

4 files changed

Lines changed: 264 additions & 1 deletion

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ Each release of Research-Kit, newest first. The version is `KIT_VERSION` in
44
`research-kit/lib/core.mjs`; a release is tagged `v<version>` (ADR-0116).
55

66
## Unreleased
7+
8+
- The README opens with an accessible workflow preview and linked CI, license,
9+
last-commit and stars badges. A contributor guide explains setup, verification,
10+
issue labels and the existing commit/PR protocol.
711
- Fixed `AGENTS.md` corpus description to use evergreen relative references rather than stale hardcoded entry counts (#299).
812

913
- The suite's "every CLI refuses a flag it does not know" table now covers `measure`,

‎CONTRIBUTING.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Contributing to Research-Kit
2+
3+
Thanks for helping make research easier to inspect and hand off. Bug fixes,
4+
documentation, useful regressions and vendor compatibility updates are welcome.
5+
The kit is feature-frozen; new commands, flags, formats, providers or checks need an
6+
ADR that lifts the freeze for that item ([ADR-0117](docs/adr/0117-feature-freeze-from-0-9-0.md)).
7+
8+
Read [AGENTS.md](AGENTS.md) before changing the repository. Its standing protocol
9+
applies to both people and agents. Use the [architecture map](docs/ARCHITECTURE.md)
10+
to find the module that owns the behavior, and the [documentation map](docs/README.md)
11+
to find the relevant guide or decision.
12+
13+
## Find a task
14+
15+
- [Good first issues](https://github.com/StepenkoAnatoli/Research-Kit/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)
16+
are small, well-defined tasks with a clear way to verify the result.
17+
- [Help wanted](https://github.com/StepenkoAnatoli/Research-Kit/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22)
18+
marks tasks where another contributor would help.
19+
- [Bugs](https://github.com/StepenkoAnatoli/Research-Kit/issues?q=is%3Aissue%20is%3Aopen%20label%3Abug)
20+
and [documentation issues](https://github.com/StepenkoAnatoli/Research-Kit/issues?q=is%3Aissue%20is%3Aopen%20label%3Adocumentation)
21+
identify the kind of change.
22+
23+
Check for an existing fix PR before starting. A short comment on the issue helps
24+
others avoid doing the same work. A good bug report includes the command, working
25+
directory, Node and Git versions, expected behavior, actual output and a minimal
26+
reproduction. Use disposable fixtures and remove credentials from the report.
27+
28+
## Set up a checkout
29+
30+
Use Node **22.22.1+ or 24+**, Git, and Python **3.11+** for the cross-language
31+
conformance tests. See [requirements](README.md#requirements) and
32+
[supported platforms](README.md#supported-platforms) for the maintained scope.
33+
The kit uses plain Node with no package install step.
34+
35+
Fork the repository, clone your fork, and create a branch for one task:
36+
37+
```sh
38+
git clone https://github.com/YOUR-USERNAME/Research-Kit.git
39+
cd Research-Kit
40+
git switch -c fix/describe-the-defect
41+
node research-kit/bin/handoff.mjs
42+
node research-kit/bin/preflight.mjs
43+
node research-kit/bin/doctor.mjs
44+
```
45+
46+
Run these commands from the checkout you intend to change. Handoff checks the
47+
received corpus, preflight checks its declared contract, and doctor describes the
48+
actual machine configuration. Record the actual verdict and chosen transport.
49+
If the existing corpus fails, follow the named remedy before building; preserve
50+
`research/raw/` and its `.fetches.jsonl` ledger. Do not rewrite captured evidence
51+
or recollect it to hide a checkout or line-ending problem.
52+
53+
## Make and verify the change
54+
55+
For a bug fix, first add a regression that reproduces the defect. Run the relevant
56+
test groups, fix the behavior, then rerun those groups. Group arguments match test
57+
file names; for example:
58+
59+
```sh
60+
node research-kit/bin/selftest.mjs machine panel
61+
node research-kit/bin/selftest.mjs
62+
node research-kit/bin/preflight.mjs
63+
node research-kit/bin/handoff.mjs
64+
node research-kit/bin/doctor.mjs
65+
git diff --check
66+
```
67+
68+
The offline suite needs no vendor key or paid collection. Tests that exercise a
69+
local browser need Chromium or Chrome; the suite reports unavailable capabilities
70+
as `UNSUP`, with their reason. Include unsupported results when reporting a run.
71+
The full suite can take around 25–30 minutes on a Windows PC. The normal commit
72+
gate runs it when a commit touches `research-kit/`; let that gate finish.
73+
74+
A red suite stops work. Record the failing test and working directory, then fix
75+
or explain the failure before continuing. Do not bypass the hooks to publish a
76+
fix that has not passed its required checks.
77+
78+
Keep these records with the change:
79+
80+
- Update `docs/ARCHITECTURE.md` in the same commit as a declared code-path change.
81+
- Update the registered test count in `research-kit/README.md` when adding or
82+
removing tests, and describe the user-visible fix under `Unreleased` in
83+
`CHANGELOG.md`.
84+
- Record a behavior decision with a rejected alternative in an ADR. An obvious
85+
bug remedy, test mechanics or wording correction can use the commit report.
86+
Research about the kit itself belongs in a nested decision project, as
87+
[AGENTS.md](AGENTS.md) explains.
88+
89+
## Write a useful commit and PR
90+
91+
Keep one commit per independently revertible task. Use a specific subject such
92+
as `fix(artifact): reject conflicting ZIP paths` or
93+
`docs: explain the contributor verification workflow`.
94+
95+
The commit or accompanying report carries the five named parts below. Describe
96+
what another reviewer needs to know, including the commands actually run:
97+
98+
```text
99+
what changed: the modules and resulting behavior
100+
why: the reproduced defect or documentation gap
101+
what it touched: files, architecture rows and decisions
102+
what you verified: verified / untested / expected, with commands and results
103+
what you got wrong and fixed: nothing to report, or the correction record
104+
```
105+
106+
For a correction, use the six fields **mistake**, **where**, **impact**, **cause**,
107+
**fix** and **verified**. The shorter report allowed for documentation and tests
108+
is described in the standing protocol in [AGENTS.md](AGENTS.md).
109+
110+
Open the PR against `main`. Link its issue with `Fixes #NUMBER`, explain the
111+
before/after behavior, and include relevant verification and any remaining
112+
limitations. Wait for the required CI jobs and respond to review comments.
113+
114+
## GitHub Actions
115+
116+
[offline-suite](https://github.com/StepenkoAnatoli/Research-Kit/actions/workflows/offline-suite.yml)
117+
runs on pull requests and `main` pushes. It checks Linux and Windows, supported
118+
Node lines, cross-language conformance, the root preflight, archive behavior and
119+
whether verification leaves the checkout clean. Its `suite` job summarizes the
120+
required results.
121+
122+
[action-pins](https://github.com/StepenkoAnatoli/Research-Kit/actions/workflows/action-pins.yml)
123+
checks pinned third-party actions weekly and on relevant workflow changes.
124+
The collector and live-collection workflows have separate purposes and may spend
125+
credits; they are documented in the [collector guide](README.md#run-the-collector-on-github).
126+
127+
## License and evidence
128+
129+
Repository code, tests and documentation use the
130+
[PolyForm Shield License 1.0.0](LICENSE). Cached third-party pages have separate
131+
rights and attribution described in [NOTICE](NOTICE). Preserve the required
132+
notices and the evidence provenance when contributing.

‎README.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
1+
![Research-Kit workflow: frame the unknowns, collect primary sources, review claims, run the gate, and hand an authored brief to a builder.](docs/assets/research-overview.svg)
2+
13
# Research-Kit
24

3-
[![offline suite](https://github.com/StepenkoAnatoli/Research-Kit/actions/workflows/offline-suite.yml/badge.svg)](https://github.com/StepenkoAnatoli/Research-Kit/actions/workflows/offline-suite.yml)
5+
[![Tests and CI](https://img.shields.io/github/actions/workflow/status/StepenkoAnatoli/Research-Kit/offline-suite.yml?branch=main&label=tests%20%26%20CI&style=flat-square)](https://github.com/StepenkoAnatoli/Research-Kit/actions/workflows/offline-suite.yml)
6+
[![License: PolyForm Shield 1.0.0](https://img.shields.io/badge/license-PolyForm%20Shield%201.0.0-2563eb?style=flat-square)](LICENSE)
7+
[![Last commit](https://img.shields.io/github/last-commit/StepenkoAnatoli/Research-Kit/main?style=flat-square&color=0d9488)](https://github.com/StepenkoAnatoli/Research-Kit/commits/main)
8+
[![GitHub stars](https://img.shields.io/github/stars/StepenkoAnatoli/Research-Kit?style=flat-square&color=f5b942)](https://github.com/StepenkoAnatoli/Research-Kit/stargazers)
9+
10+
[Quickstart](QUICKSTART.md) · [Command reference](research-kit/README.md) · [Contributing](CONTRIBUTING.md) · [Good first issues](https://github.com/StepenkoAnatoli/Research-Kit/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)
411

512
**Research first, build second.** Research-Kit gives AI agents a workflow for collecting
613
sources, declaring blocking unknowns, and handing traceable research artifacts to a builder.
@@ -45,6 +52,7 @@ through GitHub with one token, and you only read the brief.
4552
- [Supported platforms](#supported-platforms)
4653
- [Repository layout](#repository-layout)
4754
- [Documentation](#documentation)
55+
- [Contributing](#contributing)
4856
- [License](#license)
4957

5058
## How it works
@@ -680,6 +688,7 @@ docs/
680688
architecture-history/ what the architecture map used to say, and when it changed
681689
review-*.md and other dated files: past reviews, audits and build reports
682690
AGENTS.md the rules every agent follows in this repository
691+
CONTRIBUTING.md setup, verification and PR guidance for contributors
683692
CONTEXT.md the domain vocabulary
684693
CHANGELOG.md what changed in each release
685694
QUICKSTART.md the GitHub route with one token
@@ -709,6 +718,13 @@ BUNDLE_INDEX.md, RESEARCH_REPORT.md the archive this repository was receive
709718
- [`CHANGELOG.md`](CHANGELOG.md): release notes. The kit is feature-frozen since 0.9.0;
710719
it takes bug fixes, documentation, tests and vendor updates.
711720

721+
## Contributing
722+
723+
Bug fixes, documentation, regression tests and vendor compatibility updates are welcome.
724+
Start with [CONTRIBUTING.md](CONTRIBUTING.md) for setup, verification, commit reports and
725+
PR guidance. Browse the [good first issues](https://github.com/StepenkoAnatoli/Research-Kit/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)
726+
and check for an existing fix PR before starting.
727+
712728
## License
713729

714730
The code, tests and documentation are licensed under the
@@ -723,3 +739,5 @@ licence. They are other people's pages, reproduced as research evidence so that
723739
claim can be checked against the page it rests on. Copyright stays with their owners, this
724740
repository grants no licence over them, and [`NOTICE`](NOTICE) says which hosts' own
725741
licences permit redistribution with attribution. `REUSE.toml` marks those paths.
742+
743+
> *If you find this project helpful, please consider giving it a ⭐!*

‎docs/assets/research-overview.svg‎

Lines changed: 109 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)