LexiSharp/Directory.Build.props at main · manuc66/LexiSharp · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
<Project>

  <!--
    CS1591 (missing XML comment on a public member) is NOT suppressed. It used to be, set
    per project, and the suppression is gone: every package sets GenerateDocumentationFile,
    the SDK packs the resulting LexiSharp.xml into the nupkg, and that file is what a
    consumer's IntelliSense reads. A public member with no `<summary>` is therefore a hole in
    a shipped artifact rather than a style preference, and the warning is the cheapest way to
    keep it closed. The five the warning found when it was enabled are documented now, and
    the generated API reference (bench/LexiSharp.ApiDocs) reads that same XML, so a hole
    shows up there as an empty "What it is" cell.
  -->

  <!--
    Symbol packages. Portable PDBs are produced by default in Release, but they are
    discarded by the pack: setting IncludeSymbols puts each assembly's PDB in a .snupkg
    alongside the .nupkg, which is what nuget.org's symbol server expects. Applied to every
    project here (not just the packable ones) because this file is imported before each
    project body, so IsPackable is not yet defined at evaluation time; non-packable projects
    never produce a package and are unaffected.

    SourceLink is not referenced explicitly: the .NET SDK imports Microsoft.SourceLink.GitHub
    in-box, so the PDBs already carry a mapping to the repository. Verified by inspecting a
    produced .snupkg (see .github/workflows/ci.yml, "Symbol packages").
  -->
  <PropertyGroup>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>

  <!--
    Deterministic source paths. Normalizing them turns the agent's checkout directory
    into a repository-relative path inside the PDB, so a debugger that reads a published
    PDB does not resolve sources under /home/runner/work. Only in CI: it changes the path
    mapping recorded in the PDB, so applying it locally too would make local PDBs differ
    from the published ones. GitHub Actions sets CI=true.
  -->
  <PropertyGroup Condition="'$(CI)' == 'true'">
    <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
  </PropertyGroup>

  <!--
    The package version, declared once for every project. It used to be a <Version> in each
    of the four packable csproj files, and a documentation page carried the same number in
    prose, so a release meant editing five places and forgetting one: `5248329` is a commit
    whose whole content is the version being three pages stale after a release.

    Here rather than in a shared .props of its own, because this file is imported before
    every project body, so the property is set before anything can override it. That is the
    whole reason it lives here and not in a Directory.Packages.props-style import: an
    explicit <Version> in a csproj still wins, silently, and a version that only *looks*
    centralized is worse than one that was duplicated visibly. VersionTests.cs reads the four
    csproj files to keep the duplication from coming back.
  -->
  <PropertyGroup>
    <Version>0.8.0</Version>
  </PropertyGroup>

  <!--
    A warning fails the build. Nothing else here treats one as a failure: `dotnet build` fails on
    errors only, and the SonarCloud job that imports analyzer output into its own issues is skipped
    unless SONAR_TOKEN is configured, so on a repository without that secret the only reader of a
    CS1591 with no `<summary>` or of a CA rule newly enabled by an SDK bump is a person scanning a
    log. Measured when this was set, over the eleven projects in both configurations: zero warnings
    in Release, zero in Debug, so nothing had to be fixed to turn it on.

    What arrives afterwards is fixed rather than suppressed. .editorconfig records the two CA rules
    this repository refuses and why, and that file is the only place where a diagnostic is allowed
    to stop.

    NU1903, a dependency carrying a published advisory, is an error here like any other, and it
    fires when the advisory data is refreshed rather than when the source changes. That is the
    point: nothing in a commit can be expected to notice a vulnerability in a transitive package.
  -->
  <PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>

</Project>