Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (82 loc) · 4.16 KB

CONTRIBUTING.md

File metadata and controls

105 lines (82 loc) · 4.16 KB
Raw

Contributor Guide

Prerequisites

To work with the project, you'll need .NET SDK 8 or later.

Build

Use the following shell command:

$ dotnet build

Test

Use the following shell command:

$ dotnet test

On Windows, tests that create symbolic links require either Developer Mode or an elevated process. Developer Mode lets an unelevated process create symbolic links, as documented for the CreateSymbolicLinkW API. When neither is available, these tests are skipped locally; CI runners fail instead, ensuring that the tests are not silently skipped in automation.

Public API

In TruePath, we track the changes made to the public API, for the package stability purposes.

The public API of every packable project is recorded per target framework in the PublicAPI/<target framework>/ directories:

  • PublicAPI.Shipped.txt lists the API of the latest release,
  • PublicAPI.Unshipped.txt lists the changes made since then.

If you change the public API, the build-time diagnostic will report any difference as RS0000-style errors. These are warnings in local builds (for the development purpose) and errors on CI.

To update the files, either use the code fix for these diagnostics in your IDE, or run the following shell command for every changed project, e.g.:

$ dotnet format analyzers <path to project> --diagnostics RS0016 --severity info --include-generated

This command only updates one target framework per run, so you might need to run it several times.

Removed members are not handled by this command, so they need to be removed separately:

  • if the member is listed in PublicAPI.Unshipped.txt, delete that line;
  • if the member is listed in PublicAPI.Shipped.txt, add a copy of that line prefixed with *REMOVED* to PublicAPI.Unshipped.txt.

Test Documentation

To open the project documentation site locally, use the following shell commands:

$ dotnet tool restore
$ dotnet docfx docs/docfx.json --serve

Then, open http://localhost:8080/ and browse the documentation.

License Automation

If the CI asks you to update the file licenses, follow one of these:

  1. Update the headers manually (look at the existing files), something like this: 
    // SPDX-FileCopyrightText: %year% %your name% <%your contact info, e.g. email%>
//
// SPDX-License-Identifier: MIT
    (accommodate to the file's comment style if required).
  2. Alternately, use REUSE tool: 
    $ reuse annotate --license MIT --copyright '%your name% <%your contact info, e.g. email%>' %file names to annotate%

(Feel free to attribute the changes to "TruePath contributors https://github.com/ForNeVeR/TruePath" instead of your name in a multi-author file, or if you don't want your name to be mentioned in the project's source: this doesn't mean you'll lose the copyright.)

File Encoding Changes

If the automation asks you to update the file encoding (line endings or UTF-8 BOM) in certain files, run the following PowerShell script (PowerShell Core is recommended to run this script):

$ pwsh -File scripts/Test-Encoding.ps1 -AutoFix

The -AutoFix switch will automatically fix the encoding issues, and you'll only need to commit and push the changes.

GitHub Actions

If you want to update the GitHub Actions used in the project, edit the file that generated them: scripts/github-actions.fsx.

Then run the following shell command:

$ dotnet fsi scripts/github-actions.fsx