Multi Library Template

This is my best effort at creating a template for solutions that contain multiple projects, especially for libraries.

Tech Stack

Purpose	Technology
Source control	GitHub
CI/CD	AppVeyor
Documentation	XMLDoc2Markdown
Test driver	NUnit
Test converge	coveralls

Getting started

Setting up your project in 10 minutes max.

Setup environment

Create a GitHub repository and clone it
Add the repository to AppVeyor
Add the repository to coveralls
Replace variables with your specific information
Confirm your code-style in the .editorconfig

Lastly replace this README.md with your own.

Variables

There are a few variables denoted by the +++ prefix. Search all project files for this prefix.

The following files contain variables appveyor.yml, src/AssemblyInfo.cs & src/Directory.Build.props

Variable	Explanation
+++PROJECT	The root name of your project. e.g. `Microsoft` or `System`
+++YOU	The GitHub name of the owner of the project
+++VALUE	Some specific value explained in the following comment

Include documentation

./scripts/doc.ps1

The script generates the markdown documentation, then reference it in the README.md.

`Your.Project` [documentation](doc/Your.Project/index.md)

Automatically update the documentation using the following github workflow

on:
  push:
    branches:
      - /^rc/
  workflow_dispatch:

name: Update Documentation

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - name: Update documentation
        shell: pwsh
        run: scripts/doc.ps1
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: Update documentation
          file_pattern: doc/*

Solution & Projects

First add a solution in the repository root.

dotnet new sln -n "Your"

Add a projects in src/ and tests/ and define the missing nuget and assembly information, see more on project files.

dotnet new classlib -n "Your.Project"

Testadapters similar packages are already included in Build.props.

Workflow

This template assumes that there are three kinds of branches

release: Branches with this prefix trigger deploy scripts. Only one commit should exist per branch, and it should have a tag.
rc: Branches with this prefix update the doc. If they are sound, a release branch may be created.
development: Any other branch with none of the prefixes above.

Badges

The most fancy badges and build charts at buildstats.info

Happy badges at shields.io

Files

Release notes

Contains the release notes of each project. Releases are usually separated by ---. The file is automatically imported into the project package using the Build.props.

`Build.props`

This template uses Directory.Build.props to reduce the redundancy in .csproj project files. There are distinct props for both src/ and tests/ where assembly & nuget information is defined, as well as common packages are included.

This allows new projects to be added using the dotnet cli with minimal manual intervention.

License

To change the license to a file based replace PackageLicenseExpression with

    <PackageLicenseFile>../../LICENSE-MIT</PackageLicenseFile>

Scripts

These scripts/ are usually used by the CI, but can be run locally as well.

tooling.ps1: Installs required tools globally, requires the choco package manager. Can be adopted to work with linux, by installing powershell first
test.ps1: Executes all test projects in tests/, collects code coverage, and uploads it to coveralls.
doc.ps1: Generates markdown documentation from the xml documentation, generated by the build project, in the doc/ directory. One subdirectory is created per project with the same name.

`.gitignore`

The gitignore is created by topal gitignore then modified to work with VisualStudio, JetBrains Rider & VSCode.

`.editorconfig`

The EditorConfig is a bit opinionated, so you might want to change some things. There is plugin support for all moderns IDEs and VIM.

`.csproj`

Take a look at the example project and source generator example.

Tags from the Directory.Build.props are included in every .csproj in sub-directories. Duplicates are overwritten.

Documentation on project properties and stuff:

ProphetLamb/CSharpMultiLibrary