Contributing

xlnt welcomes contributions from everyone regardless of skill level (provided you can write C++ or documentation).

Getting Started

Look through the list of issues to find something interesting to work on. Help is appreciated with any issues, but important timely issues are labeled as "help wanted". Issues labeled "docs" might be good for those who want to contribute without having to know too much C++. You might also find something that the code is missing without an associated issue. That's fine to work on to, but it might be best to make an issue first in case someone else is working on it.

The XLSX format is described in ECMA-376 5th edition. Part 1 contains the most relevant information:

• A PDF with all information, especially section "18. SpreadsheetML Reference Material" may be useful. Using the outline of this section allows you to navigate to all the relevant parts of the XLSX format.

• OfficeOpenXml-XMLSCHEMA-Strict.zip > sml.xsd: contains the xsd specification of the XLSX format. This information is also available in the PDF in annex A.2 SpreadsheetML.

Specifications

In addition to ECMA-376 (see Getting Started), there are some further specifications that are relevant for specific features:

• .ZIP File Format Specification from PKWARE, Inc., version 6.2.0 (2004) for zipping and unzipping the contents of XLSX files.

• [MS-OFFCRYPTO]: Office Document Cryptography Structure, for encrypted XLSX files.

• [MS-CFB]: Compound File Binary File Format, used by encrypted XLSX files and older XLS files.

• [MS-OE376]: Office Implementation Information for ECMA-376 Standards Support, for Microsoft Excel-specific implementation details not standardized by ECMA-376.

• [MS-ODRAWXML]: Office Drawing Extensions to Office Open XML Structure, for drawings.

• [MS-OFFMACRO]: Office Macro-Enabled File Format, for macro-enabled XLSM files.

• [MS-OFFMACRO2]: Office Macro-Enabled File Format Version 2, for macro-enabled XLSM files.

There are some further specifications that have not yet been implemented in XLNT, in case anyone wants to contribute:

• ISO/IEC 29500, the ISO and IEC standardized version of ECMA-376. Exists in two versions:

  • ISO/IEC 29500 Transitional, fully supported since Microsoft Excel 2010

  • ISO/IEC 29500 Strict, supported for reading since Microsoft Excel 2010, and fully supported since Microsoft Excel 2013

• [MS-XLSX]: Excel (.xlsx) Extensions to the Office Open XML SpreadsheetML File Format, specifies extensions to the Office Open XML file formats described in ISO/IEC 29500.

• [MS-OI29500]: Office Implementation Information for ISO/IEC 29500 Standards Support, for Microsoft Excel-specific implementation details not standardized by ISO/IEC 29500.

• [MS-XLS]: Excel Binary File Format (.xls) Structure, for the older XLS format used by default in Microsoft Excel 2003 and earlier. Also see tfussell/xlnt#227 for more details.

• [MS-XLSB]: Excel (.xlsb) Binary File Format, for XLSB files, supported since Microsoft Excel 2007.

Contributions

Contributions to xlnt should be made in the form of pull requests on GitHub. Each pull request will be reviewed and either merged into the current development branch or given feedback for changes that would be required to do so.

All code in this repository is under the MIT License. You should agree to these terms before submitting any code to xlnt.

Pull Request Checklist

• Branch from the head of the current development branch. Until version 1.0 is released, this the master branch.

• Commits should be as small as possible, while ensuring that each commit is correct independently (i.e. each commit should compile and pass all tests). Commits that don't follow the coding style indicated in .clang-format (e.g. indentation) are less likely to be accepted until they are fixed.

• If your pull request is not getting reviewed or you need a specific person to review it, you can @-reply a reviewer asking for a review in the pull request or a comment.

• Add tests relevant to the fixed defect or new feature. It's best to do this before making any changes, make sure that the tests fail, then make changes ensuring that it ultimately passes the tests (i.e. TDD). xlnt uses cxxtest for testing. Tests are contained in a tests directory inside each module (e.g. source/workbook/tests/test_workbook.hpp) in the form of a header file. Each test is a separate function with a name that starts like "test_". See http://cxxtest.com/guide.html for information about CxxTest or take a look at existing tests.

Conduct

Just try to be nice--we're all volunteers here.

Communication

Add a comment to an existing issue on GitHub, open a new issue for defects or feature requests, or contact @m7913d or @doomlaur if you want.