Skip to content

Commit 7532bad

Browse files
committed
docs: complete platform-specific quick start and link first contribution
1 parent 0189d4b commit 7532bad

1 file changed

Lines changed: 23 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Public Data Sentinel
22

3+
[![Tests](https://github.com/qorud02/public-data-sentinel/actions/workflows/tests.yml/badge.svg)](https://github.com/qorud02/public-data-sentinel/actions/workflows/tests.yml)
4+
35
Catch malformed public-data extracts before they enter a spreadsheet, report, or monitoring workflow.
46

57
A small Python CLI validates CSV and JSON files against an explicit data contract. It reports the record and field that failed, preserves text identifiers such as `00123`, and produces JSON or Markdown suitable for a review or CI job.
@@ -11,20 +13,31 @@ A small Python CLI validates CSV and JSON files against an explicit data contrac
1113
Python 3.10 or newer. The application has no runtime dependencies.
1214

1315
```sh
16+
git clone https://github.com/qorud02/public-data-sentinel.git
17+
cd public-data-sentinel
18+
```
19+
20+
Windows PowerShell:
21+
22+
```powershell
1423
python -m venv .venv
15-
# macOS/Linux: source .venv/bin/activate
16-
# Windows PowerShell: .venv\Scripts\Activate.ps1
17-
python -m pip install -e .
24+
.\.venv\Scripts\python.exe -m pip install -e .
25+
.\.venv\Scripts\python.exe -m public_data_sentinel.cli examples/valid.csv --contract examples/contract.json
26+
.\.venv\Scripts\python.exe -m public_data_sentinel.cli examples/invalid.csv --contract examples/contract.json --format markdown --output report.md
1827
```
1928

20-
## Try a complete workflow
29+
macOS / Linux:
2130

2231
```sh
23-
data-sentinel examples/valid.csv --contract examples/contract.json
24-
data-sentinel examples/invalid.csv --contract examples/contract.json --format markdown --output report.md
32+
python3 -m venv .venv
33+
.venv/bin/python -m pip install -e .
34+
.venv/bin/python -m public_data_sentinel.cli examples/valid.csv --contract examples/contract.json
35+
.venv/bin/python -m public_data_sentinel.cli examples/invalid.csv --contract examples/contract.json --format markdown --output report.md
2536
```
2637

27-
The first command returns exit code **0** with three records checked and no issues. The second returns **1** and writes five issues: a negative measurement, a nonfinite number, an unsupported quality value, a duplicate station/date key, and an impossible calendar date.
38+
These commands use the virtual environment directly; activation is optional.
39+
40+
The valid-data command returns exit code **0** with three records checked and no issues. The invalid-data command returns **1** and writes five issues: a negative measurement, a nonfinite number, an unsupported quality value, a duplicate station/date key, and an impossible calendar date.
2841

2942
See the committed [passing JSON report](examples/valid-report.json) and [failing Markdown report](examples/invalid-report.md). These examples are synthetic fixtures, not observations from an institution.
3043

@@ -69,11 +82,7 @@ report = validate(
6982
assert report["valid"]
7083
```
7184

72-
Run tests:
73-
74-
```sh
75-
python -m unittest discover -s tests -v
76-
```
85+
For test commands and source-only execution, see the [contributor guide](CONTRIBUTING.md).
7786

7887
GitHub Actions tests Windows and Linux with Python 3.10, 3.12, and 3.14. See the [workflow](.github/workflows/tests.yml). Source-only execution is also possible by adding `src` to `PYTHONPATH` and running `python -m public_data_sentinel.cli`.
7988

@@ -86,6 +95,8 @@ GitHub Actions tests Windows and Linux with Python 3.10, 3.12, and 3.14. See the
8695

8796
## Contributing
8897

98+
A first contribution: [add TSV input](https://github.com/qorud02/public-data-sentinel/issues/2). The issue describes compatibility requirements and regression cases.
99+
89100
Start with the [contributor guide](CONTRIBUTING.md) for local setup, reproducible fixtures, and focused draft PRs. Check [open issues](https://github.com/qorud02/public-data-sentinel/issues) and [existing PRs](https://github.com/qorud02/public-data-sentinel/pulls) before starting.
90101

91102
한국어: [기여 안내](CONTRIBUTING.md)에서 실행·검증 방법을 확인하고, 열린 이슈와 PR에서 작업 범위를 조율해 주세요.

0 commit comments

Comments
 (0)