devlooped / oss

Basic repo configuration for my OSS projects

oss template

For my new open source projects, this is the basic repository structure and build approach I'm going to use.

Goals

1. Trivial to apply and update via dotnet-file with just two simple dotnet commands.
2. Repo instructions should just be: dotnet restore & dotnet build & dotnet test right on the repo root.

Installing

After creating an empty repo (maybe with just a readme.md), just run:

dotnet file add https://github.com/devlooped/oss

This will fetch all files from this repo template and create a .netconfig file containing all the downloaded entries.

At this point, you should add a skip value to the .netconfig file for the entries you don't want to keep up-to-date afterwards. The default skips would likely match the provided .netconfig, plus any extra files you want to modify, for example:

[file]
	url = https://github.com/devlooped/oss

# don't sync the .netconfig itself, to avoid a loop
[file ".netconfig"]
	url = https://github.com/devlooped/oss/blob/main/.netconfig
	skip

# readme is always customized for the project
[file "readme.md"]
	url = https://github.com/devlooped/oss/blob/main/readme.md
	skip

# we'll be tweaking the build, say
[file ".github/workflows/build.yml"]
	url = https://github.com/devlooped/oss/blob/main/.github/workflows/build.yml
	skip

NOTE: you can also download the raw .netconfig from this repository and run dotnet file update instead. It already contains skips for the readme.

Updating

From this point on, applying template changes is as easy as running:

dotnet file update

You can also just list detected changes with:

dotnet file changes

Automation is provided via the dotnet-file.yml workflow, which runs daily and does a dotnet file sync and creates a PR in your repository as needed, with a populated changelog to inspect the incoming changes.

Design Choices

In no particular order:

1. src folder contains Directory.Build.props and Directory.Build.targets and those contain all the customizations for the build, packaging and versioning. In the past I went crazy factoring the targets into multiple files with single purpose groupings and it bcomes quite hard to follow even for me, having written it all. So it's better to Keep Things Simple™. Logically related properties and items have a Label attribute as documentation. You can customize both by adding a Directory.props or Directory.targets, which are imported at the end of both files.

2. If a src/Directory.Packages.props is found, I turn on centrally managed package versions, but it's not required.

3. GitHub Actions are provided for the CI/CD process as follows:

   • Build: regular branch builds and PRs build. By default, build and test jobs will run on ubuntu-latest. To customize this, create a ./.github/workflows/os-matrix.json file in the repository, with the matrix to use for the build, such as ["windows-latest", "ubuntu-latest", "macOS-latest"].

   • Changelog: when a release is released (not created, but actually released), a changelog is calculated and pushed to main. The changelog.config file defines changelog generation options.

   • Release notes: when a release (either draft or final) is published, the notes are generated using the same configuration above.

   • Includes: allows using HTML includes in markdown files for easier content reuse. Readmes should include the standard footer with:

     <!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
     

4. dotnet format is enforced on builds to keep consistency with .editorconfig.

5. dependabot is configured to check for updated nuget packages daily.

6. A default strong-name key is provided by default too. If the project does not desire to strong-name the assemblies, it can be skipped as well in the .netconfig file. If present, the mentioned Directory.Build.* targets will automatically pick the file and strong name assemblies.

7. Bug template provided. No addiitonal config provided since the discussions URLs cannot be relative :(.

oss's Issues

NoTargets/Traversal SDKs now support central package versions too

So we can remove the condition on the project filename

Populate RepositoryBranch when building

Since RepositoryBranch isn't populated by SourceLink, we should pass it in from the build scripts.

This is as trivial as -p:RepositoryBranch=${GITHUB_REF#refs/*/}

Update changelog on main branch and link from packages

Keeping a permalink changelog in the main branch makes it easier for nuget package users to discover what's changing across versions.

A new workflow should be created that triggers on release.published that updates the global changelog so that it includes the newly created release.

If that release, for whatever reason, ends up not being published to nuget and is instead entirely deleted, a subsequent one would fixup the changelog anyway, so there's no harm in updating it on release publishing, rather than "released" (which only happens for non-prerelease).

Simplify version label processing

Instead of passing the entire ref like we do now with -p:VersionLabel="$GITHUB_REF.$GITHUB_RUN_NUMBER", we could already strip the initial refs/[heads|tags]/ string by just passing -p:VersionLabel="${GITHUB_REF#refs/*/}.$GITHUB_RUN_NUMBER" instead

If a project needs regular resx codegen, this can't be enabled in the project

Since we update the EmbeddedResource to have an empty generator in our Directory.Build.targets :(

Would be convenient to have a way to turn that off at the project level, like a EnableRexCodeGenerator property.

If changelog is up to date, workflow fails

If a previous label (release attempt) successfully committed a changelog, subsequent release attempts for the same label will fail since the will be no changes to commit.

Weird Visual Studio behavior on non-packable projects

Describe the Bug

A simple library project targeting .NET Standard 2.0 and not meant to be packaged, therefore not setting the PackageId property, must set the IsPackable property to false, despite what's stated in Directory.Build.Targets:

    <!-- The Sdks\NuGet.Build.Tasks.Pack\build\NuGet.Build.Tasks.Pack.targets unconditionally sets 
        PackageId=AssemblyName if no PackageId is provided, and then defaults IsPackable=true if 
        a PackageId is set (?!), meaning that by default everything is packable in Sdk-style 
        projects. 
        The Directory.Build.targets are imported after the user's project properties have been 
        read, and therefore gives us a chance to inspect if an explicit PackageId was provided, 
        before the NuGet SDK target is imported and defaults it. At this point, we can give 
        IsPackable a more sensible default, making it false if no PackageId was provided at this 
        point. -->

If IsPackable is not set to anything in the project file, Visual Studio will go into an infinite loop, triggering a design-time build of the project approximately every 2 seconds.

From what I have observed, the evaluated value of IsPackable in these design-time builds alternates between true and false (true in one build, false in the following one, repeat ad libitum).

Steps to Reproduce

Create a new Library project. No code necessary. Do not set IsPackable. Watch Visual Studio go crazy.

Expected Behavior

Visual Studio should not repeatedly trigger design-time builds for no reason.

Version Info

Bug observed adding a project to https://github.com/devlooped/ThisAssembly v1.0.9, using VS2022 v17.2.1

Additional Info

• May be related to dotnet/project-system#1457
• I will soon create a draft PR to ThisAssembly where the lamented behavior may be observed

Update a release notes and artifacts on publishing

Instead of the current flow where we need to explicitly tag via git cli to trigger our workflows, make it so that we create a release on GitHub and that triggers the changelog generation and updates the release notes automatically.

We should also build the project and upload as artifacts, so that they can be validated, before releasing (as non-prerelease).

Since there is no way to force the release created event without actually publishing it, we allow the project owner to create the release as prerelease, causing all the above to trigger, and only the final release (when changing the release from prerelease to non-prerelease) is the one that builds and pushes to nuget.org

When using central package versions, package source mapping for more than one source is required

See https://learn.microsoft.com/en-us/nuget/consume-packages/package-source-mapping.

If you don't map via nuget.config, you get warnings like:

 warning NU1507: There are 2 package sources defined in your configuration. When using central package management, please map your package sources with package source mapping (https://aka.ms/nuget-package-source-mapping) or specify a single package source. The following sources are defined: https://api.nuget.org/v3/index.json, https://pkg.kzu.io/index.json ```

Replace refs/tags/ too in addition to refs/heads/

For builds from tags, the GITHUB_REF will be refs/tags/..., so we should also account for that when determining the version prefix default.

If main branch has protection enabled, pushing changelog fails

See https://github.community/t/how-to-push-to-protected-branches-in-a-github-action/16101/29

release-notes and publish actions are failing

I might have done something terribly stupid, but I basically copied your repository as-is, added a .NET multi-target project in the root, and wanted to experiment to see how things would be.

The builds passed, although I didn't see any draft releases being created. (No pull requests were used.)

I manually added a tag and then made a release.

2 actions failed

What have I done wrong?

EDIT: Even though release-artifacts passed, I don't see a .nupkg file in the Release section. My project is a class library and has a package id defined if that matters.

When checking out for dotnet-format, checkout submodules too

If we don't checkout recursively like we do for the build step, we could fail just like https://github.com/devlooped/dotnet-file/pull/34/checks?check_run_id=2232728144