Line data    Source code

       1           0 : # .NET Core Project Template
       2             : 
       3             : A C# / .NET solution template for course term projects: a class library, a thin console app, xUnit tests, code and
       4             : documentation coverage generated with **both** ReportGenerator and the native lcov/genhtml tooling side by side,
       5             : Doxygen and DocFX API docs — **per platform (Windows and Linux/WSL)** — a MkDocs Material site, and local +
       6             : CI/CD release packaging, all driven by a handful of numbered scripts.
       7             : 
       8             : **Live site:** <https://ucoruh.github.io/vs-net-core-template/> (English) · <https://ucoruh.github.io/vs-net-core-template/tr/> (Türkçe) — one bilingual MkDocs Material site (`mkdocs-static-i18n`, language switcher in the header; the DocFX API reference lives under
       9             : [`/native/`](https://ucoruh.github.io/vs-net-core-template/native/windows/)).
      10             : 
      11             : ## 1. Start your own PRIVATE repository from this template
      12             : 
      13             : 1. Click **Use this template → Create a new repository** (green button, top right). **Do not fork**: a fork of a
      14             :    public repository cannot be made private.
      15             : 2. Choose your account, name the repository after your project, select **Private**, click **Create repository**.
      16             : 3. In your new repository: **Settings → Collaborators → Add people** → add the instructor (`ucoruh`) and your team mates.
      17             : 4. Clone it and build (below).
      18             : 
      19             : A private repository on GitHub Free has no GitHub Pages: show your project **locally** instead
      20             : (`7-build-all` + `9-open-site`, plus the `release/` folder) — see
      21             : [Showing your project without GitHub Pages](docs/guide/showing-without-pages.en.md) ·
      22             : [Türkçe](docs/guide/showing-without-pages.tr.md). Releases work on private repositories.
      23             : 
      24             : ## Status
      25             : 
      26             : [![CI](https://github.com/ucoruh/vs-net-core-template/actions/workflows/ci.yml/badge.svg)](https://github.com/ucoruh/vs-net-core-template/actions/workflows/ci.yml)
      27             : [![GitHub release badge](https://badgen.net/github/release/ucoruh/vs-net-core-template)](https://github.com/ucoruh/vs-net-core-template/releases/latest)
      28             : [![License: MIT](https://badgen.net/github/license/ucoruh/vs-net-core-template)](LICENSE)
      29             : 
      30             : ![All](docs/assets/badge_combined.svg)
      31             : ![Branch coverage](docs/assets/badge_branchcoverage.svg)
      32             : ![Line coverage](docs/assets/badge_linecoverage.svg)
      33             : ![Method coverage](docs/assets/badge_methodcoverage.svg)
      34             : 
      35             : *(Regenerated by `7-build-all`; see [Which report is which?](docs/guide/reports-explained.en.md).)*
      36             : 
      37             : ## Quick start
      38             : 
      39             : ```batch
      40             : :: Windows
      41             : 4-install-tools-windows.bat
      42             : 6-build-and-test-windows.bat
      43             : 7-build-all-windows.bat
      44             : 9-open-site-windows.bat
      45             : ```
      46             : 
      47             : ```bash
      48             : # Linux / WSL
      49             : chmod +x *.sh scripts/*.sh
      50             : ./4-install-tools-linux.sh
      51             : ./6-build-and-test-linux.sh
      52             : ./7-build-all-linux.sh
      53             : ./9-open-site-linux.sh
      54             : ```
      55             : 
      56             : `9-open-site` serves the built site at `http://localhost:8080/`; open that URL rather than double-clicking
      57             : `site/index.html`, so the embedded report frames load. Everything is documented in the guides below.
      58             : 
      59             : ## Project identity: `project.env`
      60             : 
      61             : `PROJECT_NAME=calculator`, `VERSION=2.1.2` (plus the solution/project paths). Every script and the CI workflow read
      62             : this one file; rename your project there. Release assets are named
      63             : `<project>-<version>[-<platform>[-<arch>]]-<content>[-<tool>].<ext>` (platform `windows` | `linux` | `macos`; WSL is `linux`).
      64             : 
      65             : ## Scripts: same number = same job, platform as suffix
      66             : 
      67             : | Script | Job |
      68             : |---|---|
      69             : | `1-configure-git-hooks-<platform>` | install the pre-commit hook |
      70             : | `2-create-gitignore-<platform>` | regenerate `.gitignore` (keeps the project section) |
      71             : | `3-install-package-manager-windows.bat` | Chocolatey + Scoop (Windows only) |
      72             : | `4-install-tools-<platform>` | .NET SDK, Doxygen, lcov, astyle, dotnet tools, MkDocs Material, coverxygen |
      73             : | `5-format-code-<platform>` | astyle |
      74             : | `6-build-and-test-<platform>` | fast: build + unit tests |
      75             : | `7-build-all-<platform>` | + coverage (both families), doc coverage (both), Doxygen + DocFX, app, site, `release/` |
      76             : | `8-run-app-<platform>` | run the sample app |
      77             : | `9-open-site-<platform>` | serve the site on localhost and open it |
      78             : | `10-release-<platform> [--dry-run]` | publish `release/` as a GitHub Release with `gh` |
      79             : | `11-clean-<platform>` | delete every generated folder |
      80             : 
      81             : `<platform>` is `windows` (`.bat`) or `linux` (`.sh`; native Linux and WSL). Helpers live in `scripts/`.
      82             : 
      83             : ### Old name → new name
      84             : 
      85             : | Old | New |
      86             : |---|---|
      87             : | `1-pre-commit` | `scripts/hooks/pre-commit` |
      88             : | `2-create-git-ignore.bat/.sh` | `2-create-gitignore-windows.bat` / `-linux.sh` |
      89             : | `3-install-package-manager.bat` (`.sh`) | `3-install-package-manager-windows.bat` (`.sh` folded into `4-install-tools-linux.sh`) |
      90             : | `4-install-dotnet-sdk`, `4-install-astyle`, `4-install-coverxygen`, `4-install-lcov`, `6-install-docfx-and-report-tools` | `4-install-tools-windows.bat` / `-linux.sh` |
      91             : | `5-format-code.bat/.sh` | `5-format-code-windows.bat` / `-linux.sh` |
      92             : | `7-build-app.bat/.sh` | `7-build-all-windows.bat` / `-linux.sh` (new fast loop: `6-build-and-test-*`) |
      93             : | `8-run-app.bat/.sh` | `8-run-app-windows.bat` / `-linux.sh` |
      94             : | `9-open-site.bat/.sh` | `9-open-site-windows.bat` / `-linux.sh` |
      95             : | `10-release.bat/.sh` | `10-release-windows.bat` / `-linux.sh` |
      96             : | `dotnet-env.bat/.sh` | `scripts/dotnet-env-windows.bat` / `-linux.sh` |
      97             : | `VERSION` | `project.env` |
      98             : 
      99             : ## Where outputs go (all gitignored)
     100             : 
     101             : `build/<platform>-<config>/` · `publish/<platform>-<arch>/` · `reports/<platform>/<kind>-<tool>/` (`tests-trx`,
     102             : `coverage-reportgenerator`, `coverage-lcov`, `doccoverage-reportgenerator`, `doccoverage-lcov`, `api-doxygen`,
     103             : `api-docfx`) · `site/` (MkDocs) · `site-native/` (DocFX) · `release/` (every release asset, same names as on GitHub).
     104             : 
     105             : ## Guide
     106             : 
     107             : Written for a student who has never used this toolchain, in English and Turkish:
     108             : 
     109             : | Guide | EN | TR |
     110             : |---|---|---|
     111             : | Install everything | [install.en.md](docs/guide/install.en.md) | [install.tr.md](docs/guide/install.tr.md) |
     112             : | Use this template (private repo) | [use-the-template.en.md](docs/guide/use-the-template.en.md) | [use-the-template.tr.md](docs/guide/use-the-template.tr.md) |
     113             : | From a project topic to your own project | [from-topic-to-project.en.md](docs/guide/from-topic-to-project.en.md) | [from-topic-to-project.tr.md](docs/guide/from-topic-to-project.tr.md) |
     114             : | Daily workflow (+ old→new names) | [daily-workflow.en.md](docs/guide/daily-workflow.en.md) | [daily-workflow.tr.md](docs/guide/daily-workflow.tr.md) |
     115             : | Which report is which? | [reports-explained.en.md](docs/guide/reports-explained.en.md) | [reports-explained.tr.md](docs/guide/reports-explained.tr.md) |
     116             : | Showing an HTML report inside your site | [embed-html-in-site.en.md](docs/guide/embed-html-in-site.en.md) | [embed-html-in-site.tr.md](docs/guide/embed-html-in-site.tr.md) |
     117             : | Showing your project without GitHub Pages | [showing-without-pages.en.md](docs/guide/showing-without-pages.en.md) | [showing-without-pages.tr.md](docs/guide/showing-without-pages.tr.md) |
     118             : | Releases & private repositories | [releases-and-private-repos.en.md](docs/guide/releases-and-private-repos.en.md) | [releases-and-private-repos.tr.md](docs/guide/releases-and-private-repos.tr.md) |
     119             : | Troubleshooting | [troubleshooting.en.md](docs/guide/troubleshooting.en.md) | [troubleshooting.tr.md](docs/guide/troubleshooting.tr.md) |