Skip to content

docs: trim and update .github/copilot-instructions.md #356

@sajayantony

Description

@sajayantony

Summary

Rewrite .github/copilot-instructions.md to be more concise and add guidance learned from #346 / #348 (Go-compatible JSON serialization fix).

This was originally part of PR #348 but was split out per reviewer feedback (one logical change per PR).

Motivation

The current instructions file (130 lines, ~8.7 KB) has:

  • Verbose prose that can be compressed without losing signal
  • Duplicate sections (Go→.NET table repeats translation rules from Spec & Lineage)
  • Missing guidance for serialization (OciJsonSerializer is now the required path)
  • Missing testing conventions discovered during fix: use Go-compatible JSON encoding for OCI manifests #348 (raw string JSON fixtures, round-trip testing, internal method parameter rules)
  • Sections with low value for Copilot (Copilot Prompt Hints, Non-Goals, trailing --- footer)

Proposed Changes

Trim from ~130 to ~100 lines (−28%) with these specific edits:

Remove

  • Go → .NET Guideline Quick Map table — duplicates bullets already in Spec & Lineage
  • Copilot Prompt Hints section — low signal
  • Non-Goals section — already implied by other rules
  • Public API Change Gate — mostly duplicates PR Guidance + Coding Style
  • Trailing --- footer line

Add

  • Serialization section:
    • All JSON must go through OciJsonSerializer (OrasProject.Oras.Serialization)
    • No direct JsonSerializer calls
    • Ensures Go-compatible encoding (+ not \u002B)
    • Serialization types are internal; domain types have no serialization logic
  • Testing additions:
    • Raw string literals for JSON fixtures; wire format over object factories
    • Round-trip: test serialize → deserialize and reverse through same path
  • Coding Style additions:
    • Spaces not tabs reminder (editorconfig + CI super-linter enforces)
    • No dead code — remove unreachable branches; verify with coverage
    • Name tuple elements in return types (e.g., (Descriptor Descriptor, byte[] Content))
    • Line length: clarify URLs may exceed the 120 hard limit

Condense (same content, fewer words)

  • Section headers shortened (e.g., Project SnapshotProject)
  • Bullet points tightened throughout
  • Go→C# translation rules nested under Spec & Lineage as sub-bullets

Review Notes

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions