71 lines
7.1 KiB
Markdown
71 lines
7.1 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
`BusinessMgr.sln` contains the `SaBusinessMgrCoreWebControl` administration app and `SaBusinessMgrCoreWebPortal` user portal. Shared code is divided among `SaBusMgrStandardBase`, `SaBusMgrStandardDbas`, `SaBusMgrCoreProcs`, and `SaBusMgrCoreWeb`. Tests live in `SaBusMgrTest_Control` and `SaBusMgrTest_Portal`. Web-project assets are under `Views`, `Localisation`, and `wwwroot`.
|
|
|
|
The solution also requires the sibling `..\..\Common-VS\Workspace` projects. Preserve this relative layout because BusinessMgr uses direct project references. Read the Common repository guidance when a task changes or depends on those shared projects.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
Run commands from the repository root:
|
|
|
|
```powershell
|
|
dotnet restore BusinessMgr.sln
|
|
dotnet build BusinessMgr.sln --configuration Debug
|
|
dotnet test BusinessMgr.sln --configuration Debug
|
|
dotnet run --project SaBusinessMgrCoreWebControl
|
|
dotnet run --project SaBusinessMgrCoreWebPortal
|
|
```
|
|
|
|
For the standard repository validation, run `./eng/validate.ps1`. It restores and builds the solution with the .NET CLI, runs both NUnit test projects, and performs repository checks; see `eng/README.md`.
|
|
|
|
When validation requirements, solution structure, target frameworks, test projects, package-audit scope, or required tooling 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. After code changes, run `dotnet build BusinessMgr.sln` where practical and report validation that could not be completed. Both launch profiles default to ports 5000/5001; override ports to run them together.
|
|
|
|
For changes to Common public APIs, target frameworks, packages, or shared behavior, validate the directly affected Common project before BusinessMgr. Coordinate framework upgrades across the dependency boundary. When the repositories cannot move atomically, consume a temporary compatible target from Common, migrate BusinessMgr, and remove the old Common target only after no in-scope consumer requires it.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Match existing C# conventions: tabs, braces on new lines, top-of-file `using` directives, PascalCase public members, and established `Sbm`/`Sacs` prefixes. Tests use descriptive names such as `Test_Application_ControlDatabase`. No repository-wide formatter is configured, so follow nearby code. 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 with Moq and coverlet. Add `[TestFixture]` and `[Test]` attributes, use the NUnit constraint model with `Assert.That` wherever possible, and place tests in the project matching the affected application. Run the relevant test project after a change, and run the full solution tests when the change crosses project boundaries. Several tests access configured databases and are integration-oriented; verify machine configuration and test data before assuming failures are isolated unit-test regressions.
|
|
|
|
## Change Discipline
|
|
|
|
Do not edit generated files or build output under `bin`, `obj`, or `TestResults`. Change source inputs instead. Before implementing a significant architectural change, describe the proposed design, affected projects, compatibility implications, and migration approach, then 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
|
|
|
|
Recent commits use concise subjects, usually prefixed with a release version, such as `3.0.2.1 Vehicle Classes`. Keep commits focused and use an imperative or clear feature/fix summary. Pull requests should describe scope, affected projects, configuration or database implications, and build/test results. Link relevant issues and include screenshots for changes to Razor views or portal/control styling.
|
|
|
|
## Security & Configuration
|
|
|
|
Do not commit credentials or machine secrets. Runtime startup requires `appsettings.machine.{ComputerName}.json`; keep environment-specific values local and document any new required keys in the pull request.
|