Contributing¶
Dziękujemy za zainteresowanie współtworzeniem TailoredApps Shared Components! Ten dokument opisuje proces contributingu oraz obowiązkowe wymagania dokumentacyjne.
Zasady ogólne¶
- Fork → Feature Branch → PR — nie commituj bezpośrednio na
master - Nazwa brancha:
feature/<short-name>lubfix/<short-name> - Jeden PR = jedna zmiana merytoryczna
- Wszystkie testy muszą przechodzić przed otwarciem PR
- Kod musi posiadać XML docs (summary) dla publicznych typów i metod
- Jedna przestrzeń nazw na plik, deklarowana bez bloku (
namespace TailoredApps.Shared.Xxx;). Styl wymusza.editorconfig; istniejący kod poprawisz poleceniemdotnet format style TailoredApps.Shared.slnx --diagnostics IDE0161 --severity info
Środowisko lokalne¶
Wymagany jest .NET SDK 11.0.100 lub nowszy — buduje obie platformy docelowe (net10.0 i net11.0). Testy uruchamiają się na net10.0 i net11.0, więc potrzebne są oba runtime'y. Konwencje dotyczące platform docelowych i runtime async opisuje strona Platformy docelowe i runtime async.
git clone https://github.com/tailored-apps/SharedComponents.git
cd SharedComponents
# .NET
export DOTNET_ROOT=/opt/homebrew/opt/dotnet/libexec
export PATH="$PATH:/opt/homebrew/opt/dotnet/bin"
dotnet restore
# Dokumentacja
pip install mkdocs-material
mkdocs serve # http://127.0.0.1:8000
Solution i katalog wyjściowy¶
Repozytorium używa pliku solution w formacie XML — TailoredApps.Shared.slnx (otwiera go dotnet CLI oraz Visual Studio 2022 17.13 lub nowsze).
Plik Directory.Build.props w katalogu głównym włącza UseArtifactsOutput, więc projekty nie tworzą już własnych folderów bin/ i obj/. Całość trafia do jednego, ignorowanego przez git katalogu artifacts/:
| Ścieżka | Zawartość |
|---|---|
artifacts/bin/<Projekt>/<konfiguracja>_<tfm>/ |
skompilowane biblioteki, np. artifacts/bin/TailoredApps.Shared.WebApi/release_net10.0/ |
artifacts/obj/<Projekt>/ |
pliki pośrednie |
artifacts/package/<konfiguracja>/ |
paczki NuGet (*.nupkg) wszystkich bibliotek — stąd publikuje je workflow release |
Aby wyczyścić build, wystarczy usunąć katalog artifacts/. Nową bibliotekę dodaj do solution poleceniem dotnet sln TailoredApps.Shared.slnx add <ścieżka do .csproj> — ustawienia z Directory.Build.props zostaną zastosowane automatycznie: platformy docelowe, wersja języka, nullable, metadane paczki (autor, licencja MIT, adres projektu) i generowanie paczki NuGet. Wersje paczek są w Directory.Packages.props, a nuget.config ogranicza źródła do nuget.org. Plików *.user oraz folderów .vs/, .idea/, .vscode/ nie commitujemy (są w .gitignore).
🔴 ŻELAZNA ZASADA DOKUMENTACJI¶
Każda nowa biblioteka w tym repo MUSI posiadać stronę dokumentacji w
docs/Libraries/.PR bez dokumentacji = PR odrzucony.
Wymagania dla każdej strony dokumentacji¶
Każda strona docs/Libraries/<NazwaBiblioteki>/index.md musi zawierać:
- Header + badges — nazwa biblioteki, badge NuGet i licencji
- Opis działania — po polsku 🇵🇱 i po angielsku 🇬🇧
- Instalacja —
dotnet add package ... - Rejestracja w DI — przykład z
Program.cs - Przykład użycia — realny, kompletny kod C# (nie toy example)
- API Reference — tabela/lista głównych interfejsów i klas
- 🤖 AI Agent Prompt — gotowy prompt do wklejenia w kontekst agenta AI
Aktualizacja nawigacji¶
Po dodaniu strony biblioteki zaktualizuj sekcję nav: w mkdocs.yml oraz tabelę bibliotek na docs/index.md.
Dwa języki i README pakietu¶
- Serwis ma dwa drzewa:
docs/(polskie) idocs-en/(angielskie). Każda strona istnieje w obu, pod tą samą ścieżką względną, i jest zarejestrowana wmkdocs.ymlorazmkdocs-en.yml; tabela bibliotek jest nadocs/index.mdidocs-en/index.md. Zmiana w bibliotece aktualizuje obie wersje. - Każda biblioteka ma
README.mdobok swojego csproj: czym jest pakiet, instalacja, rejestracja, przykład użycia, konfiguracja i link do strony w tym serwisie. Plik jest pakowany do paczki NuGet automatycznie (src/Directory.Build.props) i to on jest widoczny na nuget.org — do csproj nie trzeba nic dodawać. - Przykłady kodu muszą kompilować się z aktualnym kodem: nazwy typów, metod i kluczy konfiguracji sprawdzaj w źródłach, nie z pamięci.
Aplikacja demo i testy integracyjne¶
Przykładowy serwis (samples/: projekty Demo.DataModel, Demo.Services, Demo.WebApi) używa każdej biblioteki, a tests/TailoredApps.Shared.IntegrationTests
sprawdza ją przez HTTP. Nowa biblioteka trafia też do demo, razem z testem swojego scenariusza; zmiana, po której biblioteka jest używana
inaczej, aktualizuje demo. Demo działa bez sieci: zewnętrzna usługa jest podstawiana na poziomie transportu (handler HTTP), nigdy przez
zmianę biblioteki.
Szablon strony biblioteki¶
# TailoredApps.Shared.XXXXX
[](https://www.nuget.org/packages/TailoredApps.Shared.XXXXX/)
[](https://github.com/tailored-apps/SharedComponents/blob/master/LICENSE)
## 🇵🇱 Opis
[Pełny opis po polsku...]
## 🇬🇧 Description
[Full description in English...]
## Instalacja
\`\`\`bash
dotnet add package TailoredApps.Shared.XXXXX
\`\`\`
## Rejestracja w DI
\`\`\`csharp
// Program.cs
builder.Services.AddXxx();
\`\`\`
## Przykład użycia
\`\`\`csharp
// ...
\`\`\`
## API Reference
| Typ | Opis |
|-----|------|
| `IXxx` | ... |
## 🤖 AI Agent Prompt
\`\`\`markdown
## TailoredApps.Shared.XXXXX — Instrukcja dla agenta AI
Używasz biblioteki TailoredApps.Shared.XXXXX w projekcie .NET.
### Rejestracja
...
### Użycie
...
### Zasady
- ...
\`\`\`
Checklist przed otwarciem PR¶
- Kod kompiluje się bez błędów (
dotnet build) - Testy przechodzą (
dotnet test) - XML docs dodane do publicznych typów
- Strona dokumentacji w
docs/Libraries/ -
mkdocs.ymlnav zaktualizowany - Tabela na
docs/index.mdzaktualizowana -
mkdocs build --strictprzechodzi bez błędów -
dotnet build TailoredApps.Shared.slnx -c Release -p:ValidatePublicApi=trueprzechodzi (brak zmian niekompatybilnych z 2.0.0)
Zgodność publicznego API¶
Gałąź master to linia 3.0 w fazie testowej (3.0.0-preview.N): zmiany niekompatybilne są dozwolone do wydania 3.0.0, ale tylko
zamierzone. Gałąź release/2.1 to linia poprawek 2.1.x, zgodna z 2.0.0. Biblioteki TailoredApps.Shared.Mediator* są na master wyłączone
z porównania (przeszły z MediatR na ForkForward.Mediator i zmieniły nazwę z TailoredApps.Shared.MediatR*); pozostałe są nadal porównywane, żeby zmiana łamiąca nie zdarzyła się przypadkiem.
Linia 2.x musi pozostać zgodna z 2.0.0: kod skompilowany z dowolną wersją 2.x ma działać z każdą nowszą 2.x. Sprawdzenie
Build & Test PR porównuje publiczne API każdej biblioteki z paczką 2.0.0 z nuget.org i kończy się błędem przy zmianie
niekompatybilnej (usunięcie lub zmiana sygnatury publicznego typu albo składowej — CP0001, CP0002, …). Dodawanie API jest dozwolone.
- Wersję bazową ustawia
PublicApiBaselineVersionwsrc/Directory.Build.targets. - Nowa biblioteka: do pierwszego wydania dodaj w jej csproj
<SkipPublicApiValidation>true</SkipPublicApiValidation>, a po wydaniu zastąp to przez<PublicApiBaselineVersion>z numerem pierwszej wersji, w której się ukazała. - Na linii 2.x zamiast usuwać składową oznacz ją
[Obsolete]i dodaj nową; usunięcie czeka na wersję główną. - Zamierzone usunięcie na linii 3.0 zapisz w
CompatibilitySuppressions.xmlbiblioteki — składowa po składowej, żeby reszta jej API dalej była pilnowana. Plik generujedotnet build src/<Biblioteka>/<Biblioteka>.csproj -c Release -p:ValidatePublicApi=true -p:ApiCompatGenerateSuppressionFile=true; przejrzyj go przed commitem — ma zawierać tylko to, co usuwasz celowo.
Wydawanie wersji (maintainerzy)¶
Wypchnięcie tagu vX.Y.Z (lub wersji przedpremierowej, np. v2.0.0-preview.1) uruchamia workflow Create Release (.github/workflows/release.yml): buduje wszystkie biblioteki z wersją wziętą z tagu, uruchamia testy i publikuje paczki z artifacts/package/release w nuget.org. Job kończy się błędem, jeśli którejkolwiek paczki nie udało się opublikować. Workflow Release notes tworzy GitHub Release na podstawie zmergowanych pull requestów.
Paczki są publikowane przez Trusted Publishing w nuget.org — repozytorium nie przechowuje klucza API NuGet. Job prosi o token OIDC z GitHuba, a nuget.org wymienia go na klucz API ważny godzinę. Wymaga to jednorazowej konfiguracji:
| Gdzie | Ustawienie |
|---|---|
| nuget.org → menu konta → Trusted Publishing → nowa polityka | Repository Owner tailored-apps, Repository SharedComponents, Workflow File release.yml (sama nazwa pliku), Environment nuget |
| GitHub → ustawienia repozytorium → Secrets and variables → Actions | Sekret NUGET_USER: nazwa profilu w nuget.org (nie adres e-mail) konta będącego właścicielem polityki |
| GitHub → ustawienia repozytorium → Environments | Środowisko nuget; dodaj wymaganych recenzentów, aby każde wydanie czekało na akceptację |
Polityka obejmuje wszystkie paczki należące do konta lub organizacji wybranej jako jej właściciel. Ten sam plik workflow obsługuje gałęzie utrzymaniowe release/*, więc jedna polityka wystarcza dla wszystkich linii wydań.
Pytania¶
Otwórz Issue na GitHub lub skontaktuj się z maintainerami projektu.