State of the project

[jahav]

This is a short overview of the project and rough plans for the future. The project has been on hiatus for about a year during 2021/2022. I became a maintainer in September 2022.

Priorities

I have the following priorities and a rough plan for the development of ClosedXML. The priorities overlap, but it's what I generally want to concentrate on. For each release, there is a roadmap pinned discussion (see the Roadmap for 0.103), that contains desired goals for the release.

Overall, there are three areas of work:

• Code
  1. Phase 1 - Fix blocking technical debt
  2. Phase 2 - Fix regressions/bugs and deal with PR
  3. Phase 3 - Add/finish features
• Documentation
  • Write user documentation
  • Generated documentation/intelli sense (XML doc, nullability)
• Release semi-stable version
  • Needs to review existing API

If you are wondering why something wasn't done: Because I consider different thing to be a higher priority. Resources are limited and core technical debt has the higher priority than fixing bugs on a broken foundations.

Be prepared that that there likely won't be a response to an issue for a long time, unless I think that it's important or it's a fun (though I do have a recency bias). There are many things to do. There is no contract.

Code

Phase 1 - Fix blocking technical debt

OOXML is at the heart an collection of variables and functions used to transform one set of variable to another. Spreadsheets are the most universal and accessible development environment. Every semi-advanced feature of OOXML depends on it, from conditional formatting, to pivot tables. Load file, set values, apply formula, save file.

Most of the work in the past year has been to design and implement improvements for the core of ClosedXML:

• Cell value representation - value used to be stored as a string, is now strongly typed.
• Formula parsing and evaluation - new parser, new evaluation engine of a single formula, calculation chain for multiple formulas.
• Storage of workbook data - data were stored in individual cells, not in a sparse array. Less memory, faster.
• Saving - used to build DOM for whole file, instead now streams at least cell data thus no need to load to memory and faster)
• Replace System.Drawing - .NET ecosystem lost the universal library for images and fonts.
• many others, see release notes...

I expect to have critical issues done by 0.103. That doesn't mean technical debt is finished. Only the necessary core components were semi-fixed, so I can build on them.

EDIT: In the long term, I would like to remove OpenXML SDK dependency. It has served well, but ultimately it's another representation saving has to go through (representation of parts), there are memory problems (might have a workaround in 3.0) and so on. ClosedXML has started as a patcher of OpenXML SDK representation, but it's time to put away training wheels.
To that end, new writers/readers use standard XmlReader/XmlWriter where possible.

Phase 2 - Fix bugs and deal with PR

Basically house cleaning (issues, PRs). I am also of mind that it's good to fix something before adding a new feature (not so fun though).

Do a proper triage of all issues:

• Actual bug
• Half-implement feature
• Missing feature

Most reported issues are actually unimplemented or half-implemented features, not bugs.

Fix regressions, deal with PRs, duplicates, bugfixes. Intended behavior change is not a regression.

Phase 3 - Add/finish features

Pretty self-explanatory. Finish or add features. Generally concentrate on core features, not esoteric ones. Try to finish the features than add new ones.

Overall, calc engine, values, styles, workbook structure manipulation, adjust-to-content, pictures, pivot tables and charts are things I would like to work. I will rather concentrate on pivot tables than charts to increase depth of feature, rather than breadth.

Things like shapes, equations, VBA are not really priority.

Documentation

ClosedXML had (and still has) examples on wiki and in example project, but that's not really a great place for user friendly documentation. Granted, most people will use ChatGPT in the future, but doc should describe what software can do.

We now have https://docs.closedxml.io:

• documentation as a code, there can now be PR, CI pipeline and so on.
• versioned documentation. Wiki only had living version
• XML documentation - documentation can be generated from XML documentation.
• Better search - wiki search is very bare. New site can search content.

Documentation features. Add API documentation.

Stable release

ClosedXML has a large feature area, but it's often shallow, not deep. Many things are implemented for happy use case or only partially and work most of the time. Combine two, higher chance of failure. Combine 5...

The API sometimes isn't future-proof, e.g. IXLNamedRange assumes that defined name is only range, but it can be any formula, constant or a lambda function.

Go over the API surface and check every feature to evaluate API and feature maturity level. If unsuitable, change API. Good API is required to prevent future breaking changes.

Once that is done, hopefully start doing releases without big breaking changes. Currently, there is a significant amount of breaking changes. It's PITA for users, it's also rather annoying that ClosedXML.Report needs fixes so often.

Stability is good, though semver is a lie. Fun reading: https://hynek.me/articles/semver-will-not-save-you/