Skip to content

copilot-instructions.md

Latest commit

 

History

History
82 lines (59 loc) · 3.48 KB

copilot-instructions.md

File metadata and controls

82 lines (59 loc) · 3.48 KB
Raw

GitHub Copilot Instructions for voc4cat

This repository contains a SKOS vocabulary for catalysis. When reviewing pull requests, please help contributors follow these best practices:

Common PR Submission Issues

Missing Classification Under Top Concepts

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
  • 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.

Suggested response:

I noticed some new concepts in your submission. Please ensure each new concept has:

1. A `skos:broader` relationship to a parent concept
2. A chain of broader relationships that eventually reaches one of the top-level concepts

This ensures proper integration into the vocabulary hierarchy. You can check the existing vocabulary structure at https://nfdi4cat.github.io/voc4cat/ for examples.

Let me know if you need help identifying the appropriate parent concepts!

General Guidance

What Makes a Good Contribution

  • Small, focused changes: Single concept additions or small groups (~20 concepts)
  • Clear descriptions: Explain what the concepts represent and why they're needed
  • Proper classification: All concepts linked into the hierarchy
  • Use Excel workflow: Never edit .ttl files directly, only the Excel template
  • Request ID ranges: Get an ID range before adding new 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

Helpful Resources

Tone and Approach

  • Be welcoming and encouraging, especially to first-time contributors
  • Explain why something is important, not just that it's required
  • Provide concrete, actionable steps to fix issues
  • Acknowledge that GitHub's limitations (like org forks) aren't the contributor's fault
  • Offer to help if contributors have questions

What NOT to Do

  • Don't block PRs unnecessarily - some issues can be fixed post-merge
  • Don't be overly verbose - keep feedback concise and actionable
  • Don't criticize the contributor - focus on the code/process
  • Don't request changes for minor style issues in definitions
  • Don't duplicate feedback if it's already been mentioned

Priority Order

  1. Critical: Organization account issues (blocks CI)
  2. Important: Missing classification (affects vocabulary quality)
  3. Helpful: Main branch usage (improves contributor workflow)
  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.