Visitar URL original
ci: add copilot-instructions.md for AI coding agents by BrendanWalsh · Pull Request #2504 · microsoft/SynapseML · GitHub
Skip to content

ci: add copilot-instructions.md for AI coding agents - #2504

Merged
Brendan Walsh (BrendanWalsh) merged 1 commit into
masterfrom
brwals/copilot-instructions
Feb 14, 2026
Merged

ci: add copilot-instructions.md for AI coding agents#2504
Brendan Walsh (BrendanWalsh) merged 1 commit into
masterfrom
brwals/copilot-instructions

Conversation

@BrendanWalsh

@BrendanWalsh Brendan Walsh (BrendanWalsh) commented Feb 14, 2026

Copy link
Copy Markdown
Collaborator

What changes were proposed in this pull request?

Adds .github/copilot-instructions.md — a structured guide that helps AI coding agents (GitHub Copilot, Codex, Claude, Gemini) understand SynapseML's architecture and conventions.

Why this matters

SynapseML has several non-obvious patterns that AI agents consistently get wrong without explicit guidance:

  • Code generation pipeline: Python wrappers are auto-generated from Scala via the Wrappable trait. Agents try to edit generated files.
  • Scala-first architecture: Business logic goes in Scala, not Python. Agents default to editing Python.
  • Trait mixin pattern: Parameters are defined in traits, composed into transformer classes.
  • Required traits: Wrappable (for Python codegen), SynapseMLLogging (for telemetry), companion objects (for serialization).
  • Pinned tooling: black==22.3.0, scalastyle with specific rules, conventional commit PR titles.

What's covered (245 lines)

Section Content
Architecture Module map, directory layout, inter-module dependencies
Code Generation Pipeline How Wrappable → makePyFile() → _ClassName.py works, what to edit vs not
Scala Patterns Complete transformer example, parameter traits, logging, cognitive module differences
Build System sbt commands, Python style (black 22.3.0), scalastyle rules
Testing ScalaTest patterns, TestBase trait, SparkSession setup, Python test paths
CI/CD ADO vs GitHub Actions roles, PR title conventions
Common Mistakes 8 specific pitfalls with explanations

Research basis

Modeled after best practices from:

Key principle: focus on traps and non-obvious patterns that agents get wrong, not generic project descriptions.

How was this patch tested?

Documentation-only change. The file is read automatically by GitHub Copilot when working on PRs and issues in this repository.

Does this PR introduce any user-facing change?

No — improves AI-assisted development experience for contributors.

@github-actions

github-actions Bot commented Feb 14, 2026

Copy link
Copy Markdown

Hey Brendan Walsh (@BrendanWalsh) 👋!
Thank you so much for contributing to our repository 🙌.
Someone from SynapseML Team will be reviewing this pull request soon.

We use semantic commit messages to streamline the release process.
Before your pull request can be merged, you should make sure your first commit and PR title start with a semantic prefix.
This helps us to create release messages and credit you for your hard work!

Examples of commit messages with semantic prefixes:

  • fix: Fix LightGBM crashes with empty partitions
  • feat: Make HTTP on Spark back-offs configurable
  • docs: Update Spark Serving usage
  • build: Add codecov support
  • perf: improve LightGBM memory usage
  • refactor: make python code generation rely on classes
  • style: Remove nulls from CNTKModel
  • test: Add test coverage for CNTKModel

To test your commit locally, please follow our guild on building from source.
Check out the developer guide for additional guidance on testing your change.

@github-actions

github-actions Bot commented Feb 14, 2026

Copy link
Copy Markdown

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

@BrendanWalsh
Brendan Walsh (BrendanWalsh) merged commit 3db1636 into master Feb 14, 2026
6 checks passed
@BrendanWalsh
Brendan Walsh (BrendanWalsh) deleted the brwals/copilot-instructions branch February 14, 2026 06:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@BrendanWalsh