Documentation & Copilot-instruction updates (#212)

* Improve how-to-contribute (styling and PR #210 follow-up)
* Clean-up README - remove duplicate contributing guide
* Make copilot PR reviews more precise & less noisy
* Avoid PR-from-org-warning for home-organization and switch to using gh-markdown alert messages

Author: dalito

.github/copilot-instructions.md

@@ -9,15 +9,17 @@ This repository contains a SKOS vocabulary for catalysis. When reviewing pull re
 **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.
 
 **What to look for:**
-- Excel files in `inbox-excel-vocabs/` with new concepts
+- Vocabulary PRs are initiated by uploading an Excel file to
+  `inbox-excel-vocabs/` (transient: CI converts and removes it). Rely on the PR
+  description and CI validation artifacts rather than the file’s continued
+  presence in the branch.
 - Check if new concepts have `skos:broader` relationships defined
-- Verify the broader concepts eventually chain to a top concept like:
-  - Process
-  - Method
-  - Material entity
-  - Quality
-  - Role
-  - etc.
+- Verify the broader chain reaches one of Voc4Cat's top concepts:
+  - Physical entity (`voc4cat:0000180`)
+  - Non-temporal abstract entity (`voc4cat:0000181`)
+  - Temporal abstract entity (`voc4cat:0000182`)
+    - Common high-level children: Events (`voc4cat:0000183`), Actions (`voc4cat:0000184`), Processes (`voc4cat:0000185`)
+  - Attributes (`voc4cat:0000186`)
 
 **Suggested response:**
 ```
@@ -33,6 +35,31 @@ Let me know if you need help identifying the appropriate parent concepts!
 
 ## General Guidance
 
+### PR Review Style (Concise, no diff rehash)
+
+- Summarize changes in plain language: what changed and why.
+- Do not restate or quote diffs, hunks, or line-by-line changes.
+- Do not link to individual file diffs; reference files only when necessary (path + short purpose).
+- Focus feedback on correctness, classification, scope, and follow-ups rather than code excerpts.
+- Keep the review brief, actionable, and non-repetitive with what the GitHub diff already shows.
+
+### Choosing the Right Review Template
+
+Use simple heuristics based on PR intent and CI signals:
+- Use the Vocabulary template when the PR clearly introduces vocabulary changes
+  (e.g., PR description mentions an Excel upload or CI ran vocabulary
+  validation). Direct `.ttl` edits should be flagged (TTLs are CI-generated).
+- Use the Docs / CI template when changes are in `docs/**`, Sphinx config (`docs/conf.py`), `.github/workflows/**`, tooling, or other infrastructure.
+- 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.
+- Always avoid rehashing diffs; focus on correctness, classification, scope, build status, and next steps.
+
+### File Discovery Hints
+
+- Source Excel upload path: `inbox-excel-vocabs/voc4cat.xlsx` (transient; CI converts and removes it)
+- TTL files are CI-generated and read-only in reviews; use only for context
+- Glob for concept TTLs: `vocabularies/voc4cat/[0-9]*.ttl`
+- Regex for concept TTLs: `vocabularies/voc4cat/[0-9]{7}\.ttl`
+
 ### What Makes a Good Contribution
 
 - **Small, focused changes**: Single concept additions or small groups (~20 concepts)
@@ -43,11 +70,10 @@ Let me know if you need help identifying the appropriate parent concepts!
 
 ### What to Check in PRs
 
-1. **File locations**: Excel files must be in `inbox-excel-vocabs/`
-2. **File naming**: Keep as `voc4cat.xlsx`
-3. **No direct .ttl edits**: Turtle files should only be modified by CI
-4. **Documentation**: Changes should be described in PR description
-5. **Size**: Large contributions should be split into smaller PRs
+1. **Excel upload**: `inbox-excel-vocabs/voc4cat.xlsx` (if visible in the initial upload commit; CI may remove it after conversion)
+2. **No direct .ttl edits**: Turtle files should only be modified by CI
+3. **Documentation**: Changes should be described in PR description
+4. **Size**: Large contributions should be split into smaller PRs
 
 ### Helpful Resources
 
@@ -76,7 +102,74 @@ Let me know if you need help identifying the appropriate parent concepts!
 
 1. **Critical**: Organization account issues (blocks CI)
 2. **Important**: Missing classification (affects vocabulary quality)
-3. **Helpful**: Main branch usage (improves contributor workflow)
+3. **Helpful**: Main branch usage (improves contributor workflow), violation of vocabulary guidelines (assure quality)
 4. **Nice-to-have**: Documentation improvements, minor formatting
 
 Focus feedback on critical and important issues first. Mention helpful suggestions but don't insist on them for small contributions.
+
+## Review Templates
+
+Use these templates to structure PR reviews. Keep them concise. Do not quote diffs or link to specific file hunks; summarize in plain language.
+
+### Vocabulary PR Review Template
+
+Scope:
+- Additions or changes in vocabulary (Excel upload is transient; TTLs are CI-generated and should not be edited directly)
+
+```
+Summary: <1–3 sentences describing what changed and why>
+
+Classification:
+- Each concept has skos:broader and a chain to a top concept
+  (Physical entity, Non-temporal abstract entity, Temporal abstract entity [Events/Actions/Processes], Attributes)
+
+Quality:
+- PrefLabel + definition present (EN) per concept
+- No direct .ttl edits; TTL generated by CI
+- Conformance to guidelines <https://github.com/nfdi4cat/voc4cat/blob/main/docs/docs_usage/guidelines.md>:
+  British English; noun/noun-phrase form; duplicates avoided; appropriate
+  hyphenation; no slashes; definitions concise and non-circular.
+
+Suggestions (optional):
+- <brief, actionable improvements; keep it short>
+- If CI checks failed, add one bullet per failing job with a short, actionable
+  hint (e.g., "Validation failed – fix missing skos:broader for 3 concepts").
+  Do not paste logs; reference the job name/title only.
+
+Issues (optional):
+- Blocking: <list only items that must be fixed before merge>
+- Follow-ups (non-blocking): <short bullets>
+
+Next steps:
+- <what the author should do next; or "LGTM – ready to merge">
+```
+
+### Docs / CI PR Review Template
+
+Scope:
+- Area(s): docs pages, Sphinx config, CI workflow, tooling
+- Impact: user-facing docs, build pipeline, release process
+
+```
+Summary: <1–3 sentences describing what changed and why>
+
+Build / Checks:
+- Local/CI build status: <passes/fails + short note>
+- Preview/outputs: <describe availability; do not paste diffs>
+ - If CI failed, summarize failing job names and add brief, actionable hints in
+   Suggestions; avoid quoting logs.
+
+Risk / Compatibility (optional):
+- Backwards-compatibility: <low/medium/high>
+- Notable trade-offs: <short bullets>
+
+Issues (optional):
+- Blocking: <list only items that must be fixed before merge>
+- Follow-ups (non-blocking): <short bullets>
+
+Suggestions (optional):
+- <brief, actionable improvements>
+
+Next steps:
+- <what the author should do next; or "LGTM – ready to merge">
+```

.github/workflows/pr-checks.yml

@@ -38,6 +38,8 @@ jobs:
             const isFork = headRepo !== baseRepo;
             const isFromMain = headRef === 'main';
             const isFromOrg = pr.head.repo.owner.type === 'Organization';
+            const headOwnerLogin = pr.head.repo.owner.login;
+            const baseOwnerLogin = pr.base.repo.owner.login;
 
             // Log details - no user input in template literals for security
             console.log('PR number:', pr.number);
@@ -47,12 +49,16 @@ jobs:
             console.log('Is fork:', isFork);
             console.log('From main branch:', isFromMain);
             console.log('Owner type:', pr.head.repo.owner.type);
+            console.log('Head owner login:', headOwnerLogin);
+            console.log('Base owner login:', baseOwnerLogin);
 
             core.setOutput('is_fork', isFork);
             core.setOutput('is_from_main', isFromMain);
             core.setOutput('is_from_org', isFromOrg);
             core.setOutput('head_ref', headRef);
             core.setOutput('head_repo', headRepo);
+            core.setOutput('head_owner_login', headOwnerLogin);
+            core.setOutput('base_owner_login', baseOwnerLogin);
 
             return {
               isFork,
@@ -93,8 +99,9 @@ jobs:
 
             Thank you for your contribution to voc4cat!
 
-            ⚠️ We noticed that this pull request was submitted from the \`main\` branch of your fork.
-            While this works, it can cause issues:
+            > [!WARNING]
+            > We noticed that this pull request was submitted from the \`main\` branch of your fork.
+            > While this works, it can cause issues:
 
             - It makes it harder to keep your fork updated with upstream changes
             - You won't be able to work on multiple PRs at once
@@ -114,7 +121,7 @@ jobs:
             });
 
       - name: Post info about organization account
-        if: steps.check-main-branch.outputs.is_from_org == 'true'
+        if: steps.check-main-branch.outputs.is_from_org == 'true' && steps.check-main-branch.outputs.is_fork == 'true' && steps.check-main-branch.outputs.head_owner_login != steps.check-main-branch.outputs.base_owner_login
         uses: actions/github-script@v7
         with:
           script: |
@@ -142,8 +149,9 @@ jobs:
 
             const commentBody = `Hi @${username}! 👋
 
-            ⚠️ We noticed that this pull request comes from an organization account,
-            which will prevent our CI workflow from working correctly.
+            > [!CAUTION]
+            > We noticed that this pull request comes from a fork under an organization account,
+            > which will prevent our CI workflow from working correctly.
 
             GitHub does not allow the "Allow edits from maintainers" option for forks in organizations (see [discussion](https://github.com/orgs/community/discussions/5634)).
             Our CI needs this permission to commit turtle files and clean up Excel files.

README.md

@@ -17,9 +17,8 @@ It uses the [voc4cat-tool](https://github.com/nfdi4cat/voc4cat-tool) and GitHub
 ## Basic principles
 
 Voc4cat makes contributing easy for everyone with a GitHub account.
-The process is essentially *(see further below for details,
-browse through our [step-by-step guide](https://nfdi4cat.github.io/voc4cat/docs_usage/published-guidelines-v2.html#contribution-step-by-step-guide),
-or read the guide in pdf form with screenshots of each step (https://zenodo.org/records/13757351)*.
+The process is essentially *(browse through our [step-by-step guide](https://nfdi4cat.github.io/voc4cat/docs_usage/how-to-contribute.html),
+or read the guide in pdf form with screenshots of each step (https://zenodo.org/records/13757351)*:
 
 - Download the [most current vocabulary file (xlsx)](https://nfdi4cat.github.io/voc4cat/dev/voc4cat.xlsx),
 - Edit the vocabulary file in Excel,
@@ -78,44 +77,12 @@ Both services offer API access to voc4cat. Skosmos has more SKOS-specific featur
 
 To discuss about the **voc4cat**-vocabulary maintained here, create an [issue](https://github.com/nfdi4cat/voc4cat/issues).
 
-To contribute new concepts or collections or change existing ones, you may either submit your contributions as Excel/xlsx-file or (as an expert) as new/changed turtle file.
+To add new concepts or collections or change existing ones, please follow our [*"How to contribute?"*](https://nfdi4cat.github.io/voc4cat/docs_usage/how-to-contribute.html#) guide.
 
 > Small contributions like adding a single concept are as valuable as bigger ones.
 > In fact if you plan a bigger change (50+ concepts), consider splitting up the additions/changes into smaller chunks
 > with max. ~20 changes to make the review process not too hard for the reviewers and you as author.
 
-Here are the steps for submitting updates via Excel/xlsx:
-
-<details>
-
-- Get the Excel/xlsx-vocabulary file
-  - The most recent version of the vocabulary is always available via GitHub-pages https://nfdi4cat.github.io/voc4cat/dev/voc4cat.xlsx
-- Make changes to the Excel file. If you want to add something new you need to [request a range of IDs](https://github.com/nfdi4cat/voc4cat/issues/new/choose) for you.
-- Create a fork of the voc4cat repository (if you don't yet have one) or pull the latest changes to your fork (via "Sync fork" button in GUI).
-- Create a feature branch for your contribution (via GitHub GUI or `git switch -c name-of-branch`)
-  - Add the xlsx file to the feature branch into the folder `inbox-excel-vocabs`
-  - The name of the file must match the vocabulary that you want to update. So do not change the filename, but keep `voc4cat.xlsx`.
-- Create a pull request with the updated Excel-file in this repository.
-  - Please describe your changes and the motivation for the changes in the pull request note or link to an issue with this information.
-    This will help reviewers to understand the proposed change and decide about it.
-- Your pull request will be processed automatically by a CI/CD pipeline that typically finishes in less than a minute.
-- Review the artifacts/logs generated by the CI pipeline.
-  - The [workflow artifact](https://docs.github.com/en/actions/managing-workflow-runs/downloading-workflow-artifacts) will contain an updated xlsx file that is recreated from the updated turtle-files.
-- If all is good your contribution will be either
-  - directly merged by the maintainers
-  - or a discussion will be started about what else is needed
-  - or why the proposed change may not fit.
-- If you need to fix something, first pull the changes made by the action with `git pull` (or "sync" in GUI) and then commit further changes to the pull request branch in your clone.
-  - If any commits have been made by the CI pipeline, pull the changes to your repo (via "Sync fork" button in GUI) before committing any additional changes.
-
-</details>
-
-Finally, when the proposed pull request is accepted, your changes will be integrated in the vocabularies in the folder `vocabularies`.
-The vocabularies are stored in split form using one folder per vocabulary.
-Each concept, collection and concept scheme is stored in a separate file using the ID-part of the IRI as file name.
-
-See [inbox-excel-vocabs/README.md](https://github.com/nfdi4cat/voc4cat/tree/main/inbox-excel-vocabs/README.md) for a minimal example how to test the submission process.
-
 ## How to suggest improvements to the tooling & template?
 
 To discuss about the workflow for maintaining SKOS vocabularies based on this template, create an [voc4cat-template issue](https://github.com/nfdi4cat/voc4cat-template/issues).

docs/docs_usage/how-to-contribute.md

@@ -151,7 +151,7 @@ From the root directory of your cloned repo:
 
 2. Sync your fork with upstream nfdi4cat/voc4cat. Press the green "Sync fork" button which makes your fork/clone an exact copy of upstream `main` again (nfdi4cat/voc4cat). If this fails, see [](#troubleshooting).
 
-:::{dropdown} **Be careful when you "*Sync fork*" in GitHub UI.**
+:::{dropdown} Be careful when you "*Sync fork*" in GitHub UI.
 :icon: copilot-warning
 **It should look like this screenshot.** Your main branch should only be behind the forked repository (not ahead of it).
 
@@ -242,7 +242,7 @@ The downloaded Excel file consists of seven sheets:
 
 The *Concepts* sheet is where most contributions by users will be made.
 Detailed descriptions on how to properly fill these columns can be found
-in paragraph 6.6. There are nine columns used in the “*Concepts*” sheet:
+in the [guidelines](guidelines.md). There are nine columns used in the “*Concepts*” sheet:
 
 1. **Concept IRI**: Must be a valid URI. This is based on the
     Vocabulary URI (Uniform Resource Identifier) and for new
@@ -376,17 +376,21 @@ git push
 
 - Open the GitHub page of your fork `https://github.com/<your_username>/voc4cat` and - if you already created a branch for your contribution - switch to the branch.
 - Open the “inbox-excel-vocabs” folder
-- Click click on the "*Add file*" then "*Upload files*" to open a file a file submission page.
+- Click click on the "*Add file*" then "*Upload files*" to open a file submission page.
 - Upload the voc4cat.xlsx file (the file name must be exactly this).
-- Commit the uploaded file making sure that you **commit to your feature-branch** (not `main`). If you have to create a new branch, you may change the default name to a more reasonable name describing your contribution in the form `issue###_<short_title>`. 
+- Commit the uploaded file making sure that you **commit to your feature-branch** (not `main`). 
+  If you have to create a new branch, you may change the default name to a more reasonable name describing your contribution in the form `issue###_<short_title>`. 
 
 :::
 ::::
 
 **Create the pull request**
 
-The easiest way is go to the original [nfdi4cat/voc4cat](https://github.com/nfdi4cat/voc4cat) repository. 
-A notification will show up (1st screenshot) and if you click "Compare & pull request" the defaults will be correct (2nd screenshot).
+The easiest way is go to the original [nfdi4cat/voc4cat](https://github.com/nfdi4cat/voc4cat) repository.
+A notification will show up (1st screenshot).
+After clicking on "Compare & pull request" you will be asked about the source and target of your PR.
+Verify that the defaults are correct (2nd screenshot).
+If the selection box on the left does not show the upstream voc4cat repository, click on the "compare across forks" link to switch the view.
 
 ```{figure} media/create-pr-msg.png
 :alt: Screenshot of GitHub UI suggesting to create a PR from your fork
@@ -397,7 +401,7 @@ Vocabulary contribution workflow & Continuous Integration (CI) Pipeline
 ```{figure} media/selecting-source-and-target-branch-for-pr.png
 :alt: Screenshot of GitHub UI with the correct selection of source and target branch for your PR
 
-Check that the source is your feature branach and the target is `nfdi4cat/voc4cat`
+Check that the source is your feature branch and the target is `nfdi4cat/voc4cat`
 ```
 
 Here are some points to check before you finally submit the PR: