You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -9,15 +9,17 @@ This repository contains a SKOS vocabulary for catalysis. When reviewing pull re
9
9
**Problem:** New concepts in the SKOS vocabulary must be properly classified by linking them to the hierarchy through `skos:broader` relationships, eventually reaching one of the top concepts.
10
10
11
11
**What to look for:**
12
-
- Excel files in `inbox-excel-vocabs/` with new concepts
12
+
- Vocabulary PRs are initiated by uploading an Excel file to
13
+
`inbox-excel-vocabs/` (transient: CI converts and removes it). Rely on the PR
14
+
description and CI validation artifacts rather than the file’s continued
15
+
presence in the branch.
13
16
- Check if new concepts have `skos:broader` relationships defined
14
-
- Verify the broader concepts eventually chain to a top concept like:
15
-
- Process
16
-
- Method
17
-
- Material entity
18
-
- Quality
19
-
- Role
20
-
- etc.
17
+
- Verify the broader chain reaches one of Voc4Cat's top concepts:
- Common high-level children: Events (`voc4cat:0000183`), Actions (`voc4cat:0000184`), Processes (`voc4cat:0000185`)
22
+
- Attributes (`voc4cat:0000186`)
21
23
22
24
**Suggested response:**
23
25
```
@@ -33,6 +35,31 @@ Let me know if you need help identifying the appropriate parent concepts!
33
35
34
36
## General Guidance
35
37
38
+
### PR Review Style (Concise, no diff rehash)
39
+
40
+
- Summarize changes in plain language: what changed and why.
41
+
- Do not restate or quote diffs, hunks, or line-by-line changes.
42
+
- Do not link to individual file diffs; reference files only when necessary (path + short purpose).
43
+
- Focus feedback on correctness, classification, scope, and follow-ups rather than code excerpts.
44
+
- Keep the review brief, actionable, and non-repetitive with what the GitHub diff already shows.
45
+
46
+
### Choosing the Right Review Template
47
+
48
+
Use simple heuristics based on PR intent and CI signals:
49
+
- Use the Vocabulary template when the PR clearly introduces vocabulary changes
50
+
(e.g., PR description mentions an Excel upload or CI ran vocabulary
51
+
validation). Direct `.ttl` edits should be flagged (TTLs are CI-generated).
52
+
- Use the Docs / CI template when changes are in `docs/**`, Sphinx config (`docs/conf.py`), `.github/workflows/**`, tooling, or other infrastructure.
53
+
- Mixed PRs: pick the primary area of change and mention secondary impacts briefly. If vocabulary + docs both change substantially, you may include two short sections using both templates.
54
+
- Always avoid rehashing diffs; focus on correctness, classification, scope, build status, and next steps.
55
+
56
+
### File Discovery Hints
57
+
58
+
- Source Excel upload path: `inbox-excel-vocabs/voc4cat.xlsx` (transient; CI converts and removes it)
59
+
- TTL files are CI-generated and read-only in reviews; use only for context
60
+
- Glob for concept TTLs: `vocabularies/voc4cat/[0-9]*.ttl`
61
+
- Regex for concept TTLs: `vocabularies/voc4cat/[0-9]{7}\.ttl`
62
+
36
63
### What Makes a Good Contribution
37
64
38
65
-**Small, focused changes**: Single concept additions or small groups (~20 concepts)
@@ -43,8 +70,7 @@ Let me know if you need help identifying the appropriate parent concepts!
43
70
44
71
### What to Check in PRs
45
72
46
-
1.**File locations**: Excel files must be in `inbox-excel-vocabs/`
47
-
2.**File naming**: Keep as `voc4cat.xlsx`
73
+
1.**Excel upload**: `inbox-excel-vocabs/voc4cat.xlsx` (if visible in the initial upload commit; CI may remove it after conversion)
48
74
3.**No direct .ttl edits**: Turtle files should only be modified by CI
49
75
4.**Documentation**: Changes should be described in PR description
50
76
5.**Size**: Large contributions should be split into smaller PRs
@@ -80,3 +106,70 @@ Let me know if you need help identifying the appropriate parent concepts!
80
106
4.**Nice-to-have**: Documentation improvements, minor formatting
81
107
82
108
Focus feedback on critical and important issues first. Mention helpful suggestions but don't insist on them for small contributions.
109
+
110
+
## Review Templates
111
+
112
+
Use these templates to structure PR reviews. Keep them concise. Do not quote diffs or link to specific file hunks; summarize in plain language.
113
+
114
+
### Vocabulary PR Review Template
115
+
116
+
Scope:
117
+
- Additions or changes in vocabulary (Excel upload is transient; TTLs are CI-generated and should not be edited directly)
118
+
119
+
```
120
+
Summary: <1–3 sentences describing what changed and why>
121
+
122
+
Classification:
123
+
- Each concept has skos:broader and a chain to a top concept
0 commit comments