69 lines
7.4 KiB
Markdown
69 lines
7.4 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
`SaCommonVS.sln` contains the supported shared Sarand libraries. `SacsStandardBase` provides core types and utilities; `SacsStandardDbas` provides database support; `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:
|
|
|
|
```powershell
|
|
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.
|
|
|
|
Across all code files that support `//` line comments, use meaningful section comments instead of solid decorative comment lines. Format a section delimiter as `// --- Caption ---`, where the caption describes the code that follows, such as `Data Members`, `Construction`, `Properties`, `Test Support`, or another context-specific description. `Definitions` is appropriate where the following code declares classes, structs, interfaces, enums, or similar types. Reserve `Utilities` for internal methods that provide relatively simple supporting functionality; use a more specific caption for complex or domain-significant behavior. A delimiter may be followed by explanatory comments when useful. Surround the complete comment block with a blank line so it is visually separate from the preceding and following code; omit only the outside blank line that would otherwise appear directly after an opening brace or directly before a closing brace. Finish the file's main outer class or type block with `// --- The End ---` immediately before its closing brace. Leave nested or internal classes/types comment-free unless the type is complex enough to warrant sections and is at least 32 lines long; `// --- The End ---` is not required for such nested types. Do not add other delimiters where they do not clarify a distinct section. Apply this convention to new files. When an existing file receives significant modification, bring its section comments into line throughout that file as part of the same edit; small, isolated changes do not require unrelated wholesale reformatting.
|
|
|
|
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.
|
|
|
|
Use Windows CRLF line endings for C# source, Visual Studio project files, configuration files, PowerShell or command scripts, and general documentation. Use LF for web assets and files commonly consumed by Unix tooling, including SVG, HTML, CSS, JavaScript, shell scripts, and YAML. Follow `.gitattributes` as the authoritative policy. Whenever a file is created or edited, normalize that file to its required line ending as part of the edit, before validation and handoff; do not defer normalization as a separate cleanup step.
|
|
|
|
New Markdown documents containing tables must include this document-level style so header and data cells are top aligned:
|
|
|
|
```html
|
|
<style>
|
|
table th,
|
|
table td {
|
|
vertical-align: top;
|
|
}
|
|
</style>
|
|
```
|
|
|
|
## 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.
|
|
|
|
## 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.
|