microsoft / microsoft/BCQuality

Update guidance: published interfaces can also evolve via default method implementations

Open
#164 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
AL
Stars
212
Forks
121
Avg merge
3d 2h
Merged PRs (30d)
33

Description

Summary

Update the guidance page microsoft/knowledge/interfaces/extend-published-interfaces-dont-edit-them.md to reflect that AL interfaces now support default implementation methods, which can provide a non-breaking way to evolve published interfaces.

Problem

The current page recommends extending a published interface via a new interface rather than adding methods directly, because adding a method changes the contract and breaks existing implementers.

That guidance misses a newer AL capability: interface methods can now have default implementations. Adding a new method with a default implementation can allow existing implementers to remain compatible.

Requested changes

  • Update the guidance to acknowledge default interface method implementations as an additional evolution strategy.
  • Clarify when to prefer:
    • creating a new interface that extends the published interface, versus
    • adding a default method implementation to the existing interface.
  • Document tradeoffs and caveats for each approach (readability, versioning clarity, compatibility expectations, and long-term maintenance).
  • Update or add samples to show the default-method pattern alongside the existing extend-interface pattern.

Acceptance criteria

  • The page explicitly mentions default implementation methods as a non-breaking option.
  • Best-practice section explains decision criteria between extends and default methods.
  • Samples are updated/added to demonstrate the new guidance.
  • Existing guidance intent (avoiding breaking changes for implementers) remains clear.

Reference

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading microsoft/knowledge/interfaces/extend-published-interfaces-dont-edit-them.md and compare its existing extend-interface guidance with the requested default implementation approach. Update the page with decision criteria, tradeoffs, and samples for both strategies; done means all acceptance criteria are covered while the non-breaking-change intent remains clear.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
75/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.