From 8ebd33d9f037964835da8b5b06e8b557fb6df45d Mon Sep 17 00:00:00 2001 From: Andrzej Ochodek Date: Fri, 30 Oct 2026 15:24:42 +0100 Subject: [PATCH] Update CONTRIBUTING and add the community files CONTRIBUTING gets prerequisites, "comment on the issue first", the CLAUDE.md conventions for every contributor, the real shape of an error type, and the net10.0 test command with xUnit filters. CLAUDE.md states two existing practices: no parallel API variants, ConfigureAwait(false) in src. Adds the Contributor Covenant 3.0 (reports to opensource@ochodek.net), a bilingual question form first in the chooser, and SUPPORT.md. Co-Authored-By: Claude Opus 5.5 --- .github/ISSUE_TEMPLATE/0-question.yml | 35 +++++++++++ .github/pull_request_template.md | 2 +- CLAUDE.md | 2 + CODE_OF_CONDUCT.md | 85 +++++++++++++++++++++++++++ CONTRIBUTING.md | 13 ++-- SUPPORT.md | 9 +++ docs/GITHUB-SETUP.md | 2 +- 7 files changed, 142 insertions(+), 6 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/0-question.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SUPPORT.md diff --git a/.github/ISSUE_TEMPLATE/0-question.yml b/.github/ISSUE_TEMPLATE/0-question.yml new file mode 100644 index 0000000..edb042d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/0-question.yml @@ -0,0 +1,35 @@ +name: ❓ Pytanie / Question +description: Zapytaj, jak użyć pakietu lub dlaczego działa w określony sposób. / Ask how to use a package or why it behaves the way it does. +labels: [ "question" ] +body: + - type: markdown + attributes: + value: | + Możesz pisać po polsku lub po angielsku. / Polish or English is fine. + + Brakuje danych albo się nie zgadzają? Najpierw sprawdź je w [API NBP](https://api.nbp.pl/): biblioteka zwraca to, co publikuje NBP. / Data missing or different from what you expected? Check [NBP's API](https://api.nbp.pl/en.html) first: the library returns what NBP publishes. + - type: dropdown + id: package + attributes: + label: Pakiet / Package + options: + - OpenUrzednik.Core + - OpenUrzednik.Extensions.Logging + - OpenUrzednik.Diagnostics + - OpenUrzednik.Nbp + - OpenUrzednik.Nbp.DependencyInjection + - Inny / Other + validations: + required: true + - type: textarea + id: question + attributes: + label: Pytanie / Question + description: Co chcesz zrobić i czego nie wiesz? Przykład kodu mile widziany. / What are you trying to do, and what's unclear? A code sample helps. + validations: + required: true + - type: textarea + id: tried + attributes: + label: Co już próbowałem/am / What you've tried + description: Dokumentacja, przykłady, wyniki z API. / Docs, samples, API responses. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ae21f13..ec60e31 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -7,7 +7,7 @@ Closes # ## Checklist - [ ] Targets `develop` (or is a `release/X.Y` → `main` release PR, a `hotfix/*` → `main` PR, or a `merge/vX.Y.Z` → `develop` back-merge) -- [ ] `dotnet build`, `dotnet test` and `dotnet format --verify-no-changes` pass locally +- [ ] `dotnet build`, `dotnet test -f net10.0` and `dotnet format --verify-no-changes` pass locally - [ ] Tests cover new or changed behaviour, including error paths (unit + WireMock with real API payloads) - [ ] Public API has XML docs; breaking changes are called out below - [ ] Complies with the [ADRs](../docs/adr/README.md), or adds a new ADR for a changed decision diff --git a/CLAUDE.md b/CLAUDE.md index 9a88e4b..0439f11 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -112,6 +112,8 @@ Before you say a task is done, run `dotnet build`, `dotnet test -f net10.0` and - Library code stays trimming- and Native AOT-safe: the .NET targets set `IsAotCompatible`, so reflection-based APIs show up as IL2xxx/IL3xxx warnings. - Large clients are split into `partial` files by area (`NbpCurrencyExchangeRateClient.BuySell.cs`). - Messages and logs are in English. Format dates invariantly (`yyyy-MM-dd`). +- No parallel API variants: one public method per operation, returning a result; the exception style comes only through `EnsureSuccess()` / `EnsureSuccessAsync()`. +- Library code (`src/`) awaits with `ConfigureAwait(false)`. ## Testing conventions diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..bfd70c8 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,85 @@ + +# Contributor Covenant 3.0 Code of Conduct + +## Our Pledge + +We pledge to make our community welcoming, safe, and equitable for all. + +We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant. + +## Encouraged Behaviors + +While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language. + +With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including: + +1. Respecting the **purpose of our community**, our activities, and our ways of gathering. +2. Engaging **kindly and honestly** with others. +3. Respecting **different viewpoints** and experiences. +4. **Taking responsibility** for our actions and contributions. +5. Gracefully giving and accepting **constructive feedback**. +6. Committing to **repairing harm** when it occurs. +7. Behaving in other ways that promote and sustain the **well-being of our community**. + +## Restricted Behaviors + +We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct. + +1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop. +2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people. +3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits. +4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community. +5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission. +6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group. +7. Behaving in other ways that **threaten the well-being** of our community. + +### Other Restrictions + +1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions. +2. **Failing to credit sources.** Not properly crediting the sources of content you contribute. +3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community. +4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors. + +## Reporting an Issue + +Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm. + +When an incident does occur, it is important to report it promptly. To report a possible violation, e-mail **opensource@ochodek.net**. The maintainer reads every report and keeps it confidential. + +Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution. + +## Addressing and Repairing Harm + +If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped. + +1) Warning + 1) Event: A violation involving a single incident or series of incidents. + 2) Consequence: A private, written warning from the Community Moderators. + 3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations. +2) Temporarily Limited Activities + 1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation. + 2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members. + 3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over. +3) Temporary Suspension + 1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation. + 2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions. + 3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted. +4) Permanent Ban + 1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member. + 2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior. + 3) Repair: There is no possible repair in cases of this severity. + +This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/). + +Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/) + +For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion). + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3dd5325..d5e46ca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,23 @@ # Contributing to OpenUrzednik.NET +## Prerequisites + +- The [.NET 10 SDK](https://dotnet.microsoft.com/download) or later, and the .NET 8 runtime to run the `net8.0` tests. +- For the `net472` tests: Windows with .NET Framework 4.7.2 or later (CI runs them on 4.8). Building needs no .NET Framework targeting pack; the SDK brings the reference assemblies. + ## Before you start -- Check the [issues](../../issues): someone may already be working on it. +- Check the [issues](https://github.com/milten89/OpenUrzednik.NET/issues) and the [project](https://github.com/users/milten89/projects/2): someone may already be working on it. Comment on the issue before you start. - For larger changes (a new package, a change to the public API), open an issue with a proposal before you write code. It saves time on both sides. - New providers wait: work on GUS, KRS, MF or any other data source begins only after the first stable release of `OpenUrzednik.Nbp` ([ADR-0010](docs/adr/0010-provider-readiness-gate.md)). We close PRs that change the `src/OpenUrzednik.Gus`, `Krs` or `Mf` skeletons; propose a provider with the provider proposal issue form instead. ## Repository conventions -Binding architecture decisions are in [`docs/adr/`](docs/adr/README.md), and current work and priorities are in the [issues](https://github.com/milten89/OpenUrzednik.NET/issues) and the [project](https://github.com/users/milten89/projects/2). A change that contradicts an accepted ADR needs a new ADR in the same PR. +Binding architecture decisions are in [`docs/adr/`](docs/adr/README.md), and current work and priorities are in the [issues](https://github.com/milten89/OpenUrzednik.NET/issues) and the [project](https://github.com/users/milten89/projects/2). A change that contradicts an accepted ADR needs a new ADR in the same PR. The Code conventions, Testing conventions and Performance sections of [`CLAUDE.md`](CLAUDE.md) apply to every contributor; using AI tools is optional. - **`OpenUrzednikResult` / `OpenUrzednikResult` for every error that can happen during normal operation** (validation, HTTP statuses, bad responses, network errors, timeouts), instead of error handling scattered across the code. We throw exceptions only when the caller cancels, for programmer errors (a `null` argument or an undefined enum value, which a client method throws before it returns its task) and for fatal errors; a value of the right type that fails a format or range check is a returned `ValidationError`. Don't use `catch (Exception)` ([ADR-0002](docs/adr/0002-result-pattern-and-error-handling.md)). Exceptions (`OpenUrzednikException` and its subtypes) are available through `.EnsureSuccess()` / `.EnsureSuccessAsync()` for consumers who prefer the classic style; don't add parallel API variants. - **Dependencies:** the Core and provider packages have no NuGet dependencies (apart from official BCL packages for netstandard2.0); integrations with `Microsoft.Extensions.*` go into separate packages ([ADR-0004](docs/adr/0004-dependency-policy.md)). -- **`OpenUrzednikError`** is the base type for expected errors. Each concrete error derives from it and implements `Code` and `CreateException()`, which returns an exception derived from `OpenUrzednikException`. +- **`OpenUrzednikError`** is the base type for expected errors. A new error is a `sealed` class ([ADR-0011](docs/adr/0011-compatibility-policy.md)) that derives from it ([ADR-0002](docs/adr/0002-result-pattern-and-error-handling.md)), defines `public const string ErrorCode`, passes it to the base constructor and overrides `CreateException()` to return an exception derived from `OpenUrzednikException` (see `NotFoundError`). - **Provider packages** follow the patterns in `OpenUrzednik.Core`: type names, error naming and the way results are returned stay consistent. - **Document the public API** with `///` comments. `GenerateDocumentationFile` is on, so they show up in the consumer's IntelliSense. - **Tests** must not depend on real government servers in the default CI run. Test HTTP scenarios with stubs (`StubHttpMessageHandler`) and WireMock, using responses captured from the real API. Mark tests that call the real API with `[ManualFact]` / `[ManualTheory]`. They run only on request: `dotnet test tests/OpenUrzednik.IntegrationTests --explicit on`, or with the `OPEN_URZEDNIK_INTEGRATION_TEST_ENABLED` variable set. @@ -25,7 +30,7 @@ See [SECURITY.md](SECURITY.md). Don't report vulnerabilities in a public issue. 1. Fork, then branch from `develop` (`feature/…`, `fix/…`, `docs/…`, `chore/…`). 2. Target `develop`; we merge PRs with a merge commit. The `main` branch takes only release PRs (from `release/X.Y` branches) and hotfixes (see [`docs/RELEASE-PROCESS.md`](docs/RELEASE-PROCESS.md)). -3. Before opening a PR, run `dotnet test OpenUrzednik.slnx` and `dotnet format OpenUrzednik.slnx --verify-no-changes` locally. +3. Before opening a PR, run `dotnet build OpenUrzednik.slnx`, `dotnet test OpenUrzednik.slnx -f net10.0` and `dotnet format OpenUrzednik.slnx --verify-no-changes` locally. The tests run on Microsoft.Testing.Platform, so filters are xUnit's, not VSTest's `--filter`: `dotnet test tests/OpenUrzednik.Nbp.Tests --filter-class "*NbpGoldPriceClientTest"`. 4. Describe *what* and *why*, not only *how*, especially for changes in `Core`. PR descriptions and commit messages are in English ([ADR-0009](docs/adr/0009-documentation-language.md)). 5. The docs are in English. Next to the root README and the README of each published package sits a short Polish `README.pl.md` with only the informational parts: what the package is and the "unofficial" notice, installation, the quick-start example, the root package table and links to the English sections. If you change one of those parts and don't write Polish, say so in the PR; the maintainer updates the Polish file. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..28babf1 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,9 @@ +# Getting help + +- **Questions** about using the packages: open an issue with the [question form](https://github.com/milten89/OpenUrzednik.NET/issues/new?template=0-question.yml). Polish or English is fine. +- **Missing or unexpected data:** check [NBP's API](https://api.nbp.pl/en.html) first. The library returns what NBP publishes; the [OpenUrzednik.Nbp README](src/OpenUrzednik.Nbp/README.md#data-availability-and-limits) lists when NBP publishes and what the API limits are. +- **Bugs and feature requests:** use the other [issue forms](https://github.com/milten89/OpenUrzednik.NET/issues/new/choose). +- **Security vulnerabilities:** never in a public issue. See [SECURITY.md](SECURITY.md). +- **Code of conduct concerns:** see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). + +The maintainer works on this project in spare time and offers no paid support. The [Versioning and support](README.md#versioning-and-support) section says which versions get fixes. diff --git a/docs/GITHUB-SETUP.md b/docs/GITHUB-SETUP.md index 1b09437..fadc3ec 100644 --- a/docs/GITHUB-SETUP.md +++ b/docs/GITHUB-SETUP.md @@ -108,7 +108,7 @@ Release notes (`.github/release.yml`) group PRs by the **release labels**; every | `area:telemetry` | `#1D76DB` | Telemetry contract, `OpenUrzednik.Diagnostics`, `OpenUrzednik.Extensions.Logging` | | `provider:nbp` | `#FBCA04` | Affects `OpenUrzednik.Nbp` | | `provider-proposal` | `#C5DEF5` | Proposal for a new provider (issue form) | -| `question` | `#d876e3` | A question rather than a change (GitHub default) | +| `question` | `#d876e3` | A question rather than a change (GitHub default); the question form applies it | | `good first issue`, `help wanted`, `duplicate`, `invalid`, `wontfix` | GitHub defaults | As GitHub describes them | ## Milestones