7.0 KiB
Repository Guidelines
Project Structure & Module Organization
SaCommonVS.sln contains the supported shared Sarand libraries. SacsStandardBase provides core types and utilities, while SacsBusinessBase contains paired business objects; SacsStandardDbas provides database support, while SacsBusinessDbas contains their database implementations. SacsStandardProc provides process and file-processing support; SacsCoreWeb provides ASP.NET components; and SacsStandardAccounts provides accounting integrations. Supported mobile code is in SacsMobileMaui. The retained SacsMobileXamarin source is isolated in SaCommonVS.LegacyXamarin.sln for reference and is excluded from normal builds and the .NET 10 migration; see docs/legacy-xamarin.md. Tests live in SacsCoreUnitTests and generally mirror the corresponding source area under Standard.
These projects are consumed by sibling workspaces, including ..\..\BusinessMgr\Workspace, ..\..\PippinApps\Repositories\Sandtrap, and ..\..\PippinApps\Repositories\Sandalwood. Preserve the relative layout because downstream solutions use direct project references.
Build, Test, and Development Commands
Run commands from the repository root:
dotnet restore SaCommonVS.sln
dotnet build SaCommonVS.sln --configuration Debug
dotnet test SacsCoreUnitTests/SacsCoreUnitTests.csproj --configuration Debug
For the standard repository validation, including the focused spreadsheet tests, package audit, line-ending checks, and downstream BusinessMgr validation, run ./eng/validate.ps1. See eng/README.md for its deliberately scoped options.
When validation requirements, solution structure, target frameworks, test projects, package-audit scope, required tooling, or supported downstream consumers change, update eng/validate.ps1 and eng/README.md as part of the same change. Run the updated script before handoff. Do not bypass a failing validation stage without documenting the reason.
Use --configuration Release for release validation. Build the directly affected project first, then build the solution when a change affects public APIs or shared behavior. Mobile projects may require installed MAUI workloads and platform-specific tooling; report any unavailable workload separately from source failures.
For changes to Common public APIs, target frameworks, packages, or shared behavior, validate the relevant downstream solutions. Coordinate framework upgrades across dependency boundaries. When consumers cannot move atomically, temporarily multi-target shared libraries where practical, migrate consumers, and remove the old target only after no in-scope consumer requires it.
Coding Style & Naming Conventions
Match the existing C# conventions: tabs, braces on new lines, top-of-file using directives, PascalCase public members, and established Sacs, Sa, Sam, and Sax prefixes. Follow nearby code where no repository-wide formatter rule exists. Target the framework versions declared in project files. Do not upgrade frameworks or NuGet packages unless explicitly requested.
For code files that support // comments, use meaningful // --- Caption --- section delimiters and finish the main outer type with // --- The End ---. Apply this to new files and significantly edited files without reformatting unrelated code. Follow the full guidance in docs/instructions/file-editing-conventions.md.
Processes derived from SaProcess_Base must actively poll IsInterrupted during long-running loops and before expensive or blocking stages, then exit promptly when cancellation is requested.
For Markdown tables, follow the shared style in docs/instructions/file-editing-conventions.md. Follow the repository's formatter settings and remove imports only when demonstrably unnecessary, preserving intentional side effects. Follow this repository's .gitattributes for line endings and normalize each created or edited file before handoff.
Testing Guidelines
Tests use NUnit and live in SacsCoreUnitTests. Add [TestFixture] and [Test] attributes, use the NUnit constraint model with Assert.That wherever possible, and place focused tests under the directory matching the affected source component. Run the affected tests after a change and run the full test project when behavior crosses module boundaries. Some database, network, or platform tests may require external configuration; distinguish environment failures from code regressions.
Change Discipline
Do not edit generated files or build output under bin, obj, or TestResults. Change source inputs instead. Preserve public API compatibility because multiple sibling solutions consume these libraries. Before implementing a significant architectural or breaking change, describe the affected projects, compatibility implications, and migration approach and wait for agreement.
Treat every affected Git workspace as an independent change set. Check its status before editing, preserve unrelated changes, and report validation separately for each workspace.
Conversation Tracking
Read docs/topics.md and docs/component-reviews.md before starting repository review or follow-up work. Update them when a conversation identifies, starts, completes, or reprioritises work, or when a component is reviewed. Follow the tracking conventions in docs/README.md and use ISO YYYY-MM-DD dates.
Reusable Workflows and Instructions
Use $common-dotnet-change for Common API, framework, package, or shared-behavior changes that affect sibling consumers. Use $common-security-change for authentication, encryption, certificate validation, serialization, or database-query changes. Use $maui-change for SacsMobileMaui work. The shared library is indexed in docs/skills/INDEX.md; stable conventions and guidance on selecting or maintaining skills are indexed in docs/instructions/INDEX.md. Read only the relevant skill and references for the task.
At a natural handoff (work complete, PR-ready, or review wrapping up), consider whether the conversation exposed a repeated workflow or a lasting guidance gap. If there is concrete reusable value, briefly recommend or make the in-scope skill/instruction update; do not raise one-off fixes or routine minor edits as library candidates. See docs/instructions/skill-lifecycle.md.
Commit & Pull Request Guidelines
Keep commits focused and use a concise imperative or clear feature/fix summary. Pull requests should describe the behavior changed, affected projects, compatibility implications, and build/test results. Note any required configuration, database, framework, or workload changes.
Security & Configuration
Do not commit credentials, connection strings, tokens, certificates, or machine-specific secrets. Keep environment-specific configuration local. Treat changes to encryption, authentication, network certificate validation, serialization, and database query construction as security-sensitive and include focused validation.