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) |