Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
140 lines (90 loc) · 7.62 KB

CONTRIBUTING.md

File metadata and controls

140 lines (90 loc) · 7.62 KB
Raw

Contributing to UltimateAuth

Thank you for your interest in UltimateAuth! 💜

UltimateAuth is a community-first, open-source authentication and authorization framework for modern .NET applications. Contributions of every size are welcome: questions, bug reports, ideas, documentation, examples, tests, code, and thoughtful feedback.

You do not need to be an expert to contribute. Our goal is to make collaboration approachable, constructive, and enjoyable.

Join the community

  • GitHub Issues — report bugs and suggest improvements.
  • GitHub Discussions — ask questions and explore ideas, when discussions are enabled.
  • Discord — meet contributors, ask for help, and share feedback.

If you are unsure where to start, open an issue or say hello on Discord.

Reporting bugs and suggesting features

A good title and a short, clear description are usually enough to get started. Templates are helpful, but not mandatory.

For bug reports, please share whatever you can:

  • What you expected to happen and what actually happened.
  • The UltimateAuth version, .NET version, and relevant client/runtime, if known.
  • A small reproduction, code snippet, logs, or steps to reproduce, if available.

For feature ideas, describe the problem you want to solve and how you imagine the feature helping users.

Please do not post passwords, tokens, private keys, personal data, or sensitive logs. If you believe you found a security vulnerability, use the private process in SECURITY.md rather than opening a public issue.

Pull requests

We welcome pull requests, including small fixes and improvements.

  1. Fork the repository and create a branch for your work.
  2. Make a focused change, with tests when practical.
  3. Open a pull request targeting the dev branch.
  4. Use a descriptive title and explain what changed and why.

There is no strict pull request format. If a change fixes an issue, feel free to link it. Draft pull requests and work-in-progress discussions are welcome.

For substantial architectural changes or new authentication behavior, opening an issue first is encouraged so we can align on the approach and avoid wasted effort. This is a recommendation, not a barrier to proposing ideas.

Maintainers may suggest revisions, request tests, or help refine the approach. Reviews are intended to improve the contribution, not discourage contributors.

Building and testing

The repository contains the UltimateAuth.slnx solution and unit/integration test projects.

From the repository root, you can try:

dotnet restore UltimateAuth.slnx
dotnet build UltimateAuth.slnx
dotnet test UltimateAuth.slnx

Some integration tests or samples may require additional configuration or infrastructure. If a command fails or you cannot run a test, simply mention it in your pull request. You do not need a perfect local environment to start contributing.

Architecture and security

UltimateAuth separates authentication, authorization, sessions, credentials, domain responsibilities, and client/runtime adaptation.

Before making a substantial architectural or security-sensitive change, please read:

These documents guide architectural decisions; they are not intended to prevent questions, alternative proposals, or constructive discussion. If you believe an architectural rule should change, raise the proposal for maintainer review rather than silently bypassing it.

Security-sensitive changes may need more thorough review and regression tests than routine changes.

Using AI-assisted tools

AI tools are welcome as development aids. Contributors remain responsible for understanding their changes, reviewing generated code, and accurately describing what was tested.

Please do not submit unreviewed generated changes or claim that tests were run when they were not.

Licensing

UltimateAuth is licensed under the Apache License 2.0. By contributing, you agree that your submitted contributions may be incorporated into the project under its applicable contribution and licensing terms.

If a separate contributor agreement is introduced, its requirements will be documented before enforcement.

Contributor License Agreement (CLA)

UltimateAuth welcomes contributions from the open-source community.

Contributors retain copyright ownership of their original contributions unless otherwise agreed in writing.

By submitting a contribution, contributors agree that their contributions are provided under the project's Apache License, Version 2.0, and confirm that they have the necessary rights to submit them.

UltimateAuth intends to adopt the .NET Foundation Contributor License Agreement (CLA) process if accepted as a .NET Foundation project.

Once the CLA process is implemented, contributors may be required to sign the applicable agreement before their pull requests can be merged.

A welcoming community

Be respectful, assume good intentions, and help others learn. Different experience levels and perspectives make the project better.

Thank you for helping build UltimateAuth.

Framework targeting and CI

UltimateAuthTargetFrameworks in Directory.Build.props is the supported library framework list. Keep it unique and in ascending version order. The last entry becomes UltimateAuthLatestTargetFramework, which all five test projects inherit from tests/Directory.Build.props. Tests, including rate-limiting compatibility tests, run once on that latest framework; older frameworks receive package build verification rather than repeated test runs.

The 33 library projects under src/ and the packable Sample.Seed project use UltimateAuthBuildTargetFrameworks, which defaults to the supported list. CI can select a supported build subset through that property without changing the frameworks of single-target applications. Sample.Shared.Hub is a separate, packable net10-only Razor library. Applications, other samples, docs, and the two build tools retain their explicit net10 targets. Docker builds also restrict library builds to their net10 application target, so adding a newer library framework does not require upgrading those container SDKs.

The CI policy job queries evaluated MSBuild properties for every project. It checks solution membership, all expected library targets, and latest-only test targets, then generates the compatibility matrix and an exact package/framework table in the job summary. Each matrix job pins global.json in its own checkout to the SDK installed for its framework, so a newer preinstalled SDK cannot hide an older-SDK build failure. The committed global.json still selects MTP without pinning an SDK.

The test job retains the full solution build, but builds libraries only for the latest framework and the frameworks needed by intentional single-target projects. Identity Lab keeps its separate PostgreSQL job, TRX output, and assembly-scoped coverage. The publishing workflow also derives its SDK list from the central property.

For example, changing the central list to net10.0;net11.0 automatically generates two SDK build jobs and moves all regular tests to net11. No workflow matrix edits are needed. Framework-specific package references (notably Blazor, EF Core, and TestHost) still need compatible versions when adding a new framework. Retarget net10-only application/tool exceptions before eventually removing net10 itself; CI rejects that omission rather than silently excluding projects.