|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Module Organization |
| 4 | + |
| 5 | +This repository contains a .NET solution for exposing Notion tasks as an iCalendar feed. |
| 6 | + |
| 7 | +- `Notion2Ical/`: main library targeting `net10.0`. |
| 8 | +- `Notion2Ical/NotionApi/`: DTOs that map responses from the Notion API. |
| 9 | +- `Notion2Ical/ICalendar/`: output models used to generate iCalendar data. |
| 10 | +- `Notion2Ical/Interfaces/`: public service and repository contracts. |
| 11 | +- `Notion2Ical.Tests/`: xUnit unit tests. |
| 12 | +- `.github/workflows/ci.yml`: CI workflow for restore, build, test, and NuGet packing. |
| 13 | + |
| 14 | +## Build, Test, and Development Commands |
| 15 | + |
| 16 | +Use .NET 10. If the local shell does not resolve it, run `source ~/.zshrc` first. |
| 17 | + |
| 18 | +```bash |
| 19 | +dotnet restore Notion2Ical.sln |
| 20 | +dotnet build Notion2Ical.sln |
| 21 | +dotnet test Notion2Ical.sln |
| 22 | +dotnet pack Notion2Ical/Notion2Ical.csproj --configuration Release --output artifacts |
| 23 | +``` |
| 24 | + |
| 25 | +`dotnet test` runs the full unit test suite. `dotnet pack` creates a local NuGet package in `artifacts/`. |
| 26 | + |
| 27 | +## Coding Style & Naming Conventions |
| 28 | + |
| 29 | +Use modern C# style: file-scoped namespaces, nullable reference types, implicit usings, and project-level global usings. Keep local `using` directives out of source files unless a file-specific import is genuinely clearer. |
| 30 | + |
| 31 | +Use PascalCase for public types and members. Keep DTOs in `NotionApi` and iCalendar output types in `ICalendar`; do not mix input and output models in the same namespace. |
| 32 | + |
| 33 | +Prefer `System.Text.Json` over `Newtonsoft.Json`. |
| 34 | + |
| 35 | +## Testing Guidelines |
| 36 | + |
| 37 | +Tests use xUnit. Place tests in `Notion2Ical.Tests/` and name files after the unit under test, for example `NotionServiceTests.cs`. |
| 38 | + |
| 39 | +Test names should describe behavior, e.g. `GetVCalendarData_SkipsTasksWithoutDueDate`. Avoid tests that call the real Notion API; use fakes or custom `HttpMessageHandler` implementations. |
| 40 | + |
| 41 | +## Commit & Pull Request Guidelines |
| 42 | + |
| 43 | +Follow the existing commit style: short, descriptive, imperative or present-tense messages, such as `Refactor Notion calendar feed`. |
| 44 | + |
| 45 | +Pull requests should include a concise summary, test results, and any configuration or migration notes. Link related issues when applicable. For behavior changes, mention the affected feed output or Notion API assumptions. |
| 46 | + |
| 47 | +## Security & Configuration Tips |
| 48 | + |
| 49 | +Never commit Notion tokens, database IDs for private workspaces, or NuGet API keys. Use application configuration for `NotionCalendarOptions` and GitHub Secrets for future package publishing. |
| 50 | + |
| 51 | +TokenSave may be available, but verify its worktree before relying on results. |
0 commit comments