Repository navigation
Record settled design decisions for contributors - #24
Merged
Merged
Conversation
Several settled decisions are written down nowhere in the repository, so a contributor or an AI assistant working here has to rediscover them or reopens them. - Add a Design decisions section to AGENTS.md: who approves public changes, services staying in this repository, what adding a service takes, why generic settings resolve in the core, and the Mg prefix convention. Record why boolean settings have no typed parameters. - Add three changelog conventions: placeholders that never worked, input the documented format never supported, and result values that depend on the service's response. - Add a section on the wiki's conventions. - Explain in RELEASING.md why develop does not allow GitHub's rebase merge, and how to get a clean history instead. - Explain at enum MessagingService why it is an enum rather than a string parameter with an argument completer. Contributor documentation only, so there is no changelog entry.
Every change has to reach develop through a pull request, even a documentation edit whose tests already passed locally, so the maintainer waits on a test run before merging that adds little. Keep pull requests required for main and for contributors. Let the maintainer's own changes that a test run before merging wouldn't benefit go straight to develop after a local test run; the Tests workflow still runs on the push. Keep pull requests for squashing a branch. Contributor documentation only, so there is no changelog entry.
Sekers
force-pushed
the
feature/record-design-decisions
branch
from
October 5, 2026 18:45
c9110c2 to
4b4c5c2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Nothing changes for someone using the module. This writes down decisions that are settled but recorded nowhere in the repository, so contributors and AI assistants stop rediscovering or reopening them:
Mgprefix that shows which layer owns a setting.developdoesn't allow GitHub's rebase merge (it drops commit signatures), and how to get a clean history instead. Also, pull requests stay required formain, but the maintainer may commit straight todevelopwhen a test run before merging wouldn't help, such as for documentation.enum MessagingServicesaying why it's an enum rather than a string parameter with an argument completer. The code itself is unchanged.The wiki section mentions the wiki's
.markdownlint.jsonand itsMicrosoft-Graph.mdpage, which arrive with the wiki update that follows the next release.No live testing: nothing here touches Microsoft Graph.
Release classification
Checklist
develop, ormainfor a hotfixCHANGELOG.mdhas an entry in the right section under[Unreleased](added if missing), or the change is not user-visible.\Tests\Invoke-Tests.ps1passes🤖 Generated with Claude Code