Developers Experience

Developers Experience

We welcome contributions to the mycelium-hypha codebase. Please read the Contribution guidelines, fork, branch off development, keep the branch rebased, and open a pull request back into development. Never work directly on development or main. Commit subjects follow [Verb] <summary>; fixes #<n>.

Solution layout

mycelium-hypha.sln is a classic, flat solution (net10.0, NUnit) with four solution folders and eight projects:

tools/
├── metamodel-gen/  Hypha.MetamodelGen, Hypha.MetamodelGen.Tests
├── knowledge-gen/  Hypha.Knowledge, Hypha.Knowledge.Tests
└── hypha-cli/      Hypha.Tools, Hypha.Tools.Tests, Hypha.Tools.Hook, Hypha.Tools.Hook.Tests

tools/spec-extract/ is a separate Python project (Python ≥ 3.12), not part of the .NET solution.

Build and test

.NET, from the repository root:

dotnet build mycelium-hypha.sln
dotnet test mycelium-hypha.sln
dotnet test mycelium-hypha.sln --filter "FullyQualifiedName~MetamodelClosureTests"   # one fixture/test
dotnet test mycelium-hypha.sln --filter "TestCategory=Live"   # [Explicit]: really fetches from GitHub

Nothing reaches the network in a normal run. TestCategory=Live is [Explicit], so it never runs in CI; set GITHUB_TOKEN before running it yourself (the anonymous GitHub API allows 60 requests/hour).

Python, from tools/spec-extract/ – see Generation Pipelines for the full setup and layer breakdown.

The CLI generates, the tests verify

This is the load-bearing convention in the repository: generation is driven by [[the hypha CLI|Hypha-CLI]], never by the test runner. No test writes into knowledge/ – running dotnet test leaves the working tree clean, and a test that dirties it is treated as a bug.

KnowledgeRegenerationTests proves this without a committed baseline to diff against: it fetches a release fresh and regenerates it twice into independent scratch folders (via HyphaKnowledgeOptions.OutputRoot), then compares the two runs byte for byte against each other, proof the generators are deterministic, not that they match some fixed answer. The one real "matches-a-known-good-baseline" check left is Hypha.MetamodelGen.Tests' Expected/ golden files, held against the committed XMI test fixture and re-blessed by hand via its [Explicit] Bless_expected_files tests after an intended format change.

Determinism

Anything generated must be byte-stable: collections sort with StringComparer.Ordinal, output is LF (.gitattributes pins knowledge/** eol=lf), and nothing includes timestamps, machine paths or culture-sensitive formatting. JSON uses System.Text.Json with fixed options and \r\n → \n normalization.

Conventions

• Git workflow: branch GH<issue-number> off development; PR back into development; ask before committing or pushing.
• C#: block-scoped namespaces with usings inside the namespace, one public type per file, NUnit, the classic mycelium-hypha.sln. Every source file opens with the Apache-2.0 <copyright> header (Starion Group S.A.).
• C# dependencies and DI: prefer a maintained NuGet package over hand-rolling infrastructure. Services are registered through Microsoft.Extensions.DependencyInjection and resolved rather than constructed. Anything a caller can vary belongs on HyphaKnowledgeOptions, not as another optional parameter; anything worth watching goes through ILogger, not Console.
• Python: ruff-clean, standard-library-friendly; each file carries the # Copyright … / # SPDX-License-Identifier: Apache-2.0 header.
• Prose/docs use a spaced en dash (–), not an em dash.

Continuous integration

GitHub Actions run on every push and pull request:

• build-test-sonar.yml: Ubuntu runner; sets up JDK 17 (for SonarQube), .NET 10 and Python 3.12 with the spec-extract virtualenv; runs dotnet restore/build/test with coverage, then asserts git diff --exit-code is clean after the test run, the CI-enforced version of "the CLI generates, the tests verify" above. Also runs ruff check and pytest --cov for the Python side, wrapped in a SonarQube analysis (project key mycelium-cmbse_mycelium-hypha).

See Build and Release for the release and hook-binary workflows, which run only on manual dispatch.