Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
90 lines (57 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

90 lines (57 loc) · 4.15 KB
Raw

Contributing to CellSharp

Thanks for taking the time to contribute. Bug reports, documentation improvements, tests, fixes, and well-scoped features are all welcome.

CellSharp is currently maintained by Angelo Collura. The project aims to stay useful and predictable without becoming a wrapper for every Excel or OpenXML feature.

Please follow the Code of Conduct in all project spaces.

Before opening an issue

Before reporting a problem, please:

  • Check whether it has already been reported.
  • Reproduce it with a recent version of CellSharp when possible.
  • Include a minimal reproduction, target framework, .NET version, and CellSharp version.
  • Describe the expected behavior and the actual behavior.
  • Share an XLSX file only when it can be made public and contains no sensitive data.

Use a public issue for reproducible bugs and non-sensitive discussion. Do not use issues to report undisclosed security vulnerabilities; see SECURITY.md.

Feature requests

Feature requests are welcome when they fit CellSharp's direction:

  • Strongly typed, schema-first APIs.
  • A simple and predictable public surface.
  • DocumentFormat.OpenXml kept as an internal implementation detail.
  • Reasonable backwards compatibility.
  • Native Excel features where they are appropriate, rather than unnecessary simulation.

Please explain the problem, a concrete use case, and any alternatives considered. Discuss a large API or behavior change before investing in a substantial pull request. CellSharp intentionally does not aim to expose every Excel feature.

Pull requests

Keep pull requests focused and avoid unrelated refactoring. A pull request should:

  • Preserve compatibility when practical and explicitly call out breaking changes.
  • Add or update tests when behavior changes; bug fixes should ideally include a regression test.
  • Update relevant user documentation when a public API or behavior changes.
  • Follow the existing code style.
  • Keep OpenXML types out of the public API.
  • Build and test successfully before review.

The maintainer may request changes before merging. Review timing is best effort; no review-time commitment is implied.

Dependency updates

Dependabot remains enabled for NuGet packages and GitHub Actions. Its pull requests are review signals: inspect the proposed update, then reproduce the approved change in a maintainer-authored branch and pull request. Do not merge Dependabot pull requests directly.

Development setup

CellSharp targets netstandard2.0 and net8.0; the tests and samples target net8.0. From the repository root:

dotnet restore CellSharp.sln
dotnet build CellSharp.sln --configuration Release --no-restore
dotnet test CellSharp.sln --configuration Release --no-build

Use dotnet pack src/CellSharp/CellSharp.csproj --configuration Release --no-build when a package check is relevant to the change.

Tests

Functional changes need behavior-level coverage. XLSX tests should verify the public result and, where needed, the OpenXML structure generated by CellSharp. Do not change an existing test merely to hide a regression.

API design principles

  1. Keep the common case simple.
  2. Prefer strongly typed APIs.
  3. Keep OpenXML internal.
  4. Fail early for invalid schema or configuration.
  5. Preserve backwards compatibility when practical.
  6. Avoid unnecessary public types.
  7. Use native Excel features when appropriate instead of simulating them unnecessarily.

Commit messages

Use clear, descriptive commit messages. Conventional Commits are not required.

Maintainer

CellSharp is currently maintained by Angelo Collura. For normal project discussion, use GitHub Issues when appropriate.

Supporting the project

Contributions of code, bug reports, documentation, and feedback are already valuable support. If you prefer to contribute financially, you can do so voluntarily through Ko-fi. Donations do not affect pull request decisions, the roadmap, or technical decisions.

License of contributions

By contributing to CellSharp, you agree that your contribution may be distributed under the project's MIT License. No contributor license agreement is required.