This project started as a little excuse to exercise some of the cool new C++11 features. Over time, people actually started to use the JSON library (yey!) and started to help improve it by proposing features, finding bugs, or even fixing my mistakes. I am really thankful for this and try to keep track of all the helpers.
To make it as easy as possible for you to contribute and for me to keep an overview, here are a few guidelines which should help us avoid all kinds of unnecessary work or disappointment. And of course, this document is subject to discussion, so please create an issue or a pull request if you find a way to improve it!
Usually, all issues are tracked publicly on Github. If you want to make a private report (e.g., for a vulnerability or to attach an example that is not meant to be publisheed), please send an email to mail@nlohmann.me.
Please create an issue, assuming one does not already exist, and describe your concern. Note you need a GitHub account for this.
If you want propose changes to the code, you need to download the re2c
tool.
Clearly describe the issue:
There are currently two files which need to be edited:
src/json.hpp.re2c
(note the .re2c
suffix) - This file contains a comment section which describes the JSON lexic. This section is translated by re2c
into file src/json.hpp
which is plain “vanilla” C++11 code. (In fact, the generated lexer consists of some hundred lines of goto
s, which is a hint you never want to edit this file...).
If you only edit file src/json.hpp
(without the .re2c
suffix), your changes will be overwritten as soon as the lexer is touched again. To generate the src/json.hpp
file which is actually used during compilation of the tests and all other code, please execute
make re2c
To run re2c
and generate/overwrite file src/json.hpp
with your changes in file src/json.hpp.re2c
. We currently use re2c version 0.16. Please also use this version, because other re2c versions tend to create code that differs a lot from which makes diffs unusable.
test/src/unit.cpp
- This contains the Catch unit tests which currently cover 100 % of the library's code.
If you add or change a feature, please also add a unit test to this file. The unit tests can be compiled and executed with
make check
The test cases are also executed with several different compilers on Travis once you open a pull request.
Please understand that I cannot accept pull requests changing only file src/json.hpp
.
make pretty
which runs Artistic Style to fix indentation. If possible, run it before opening the pull request. Otherwise, we shall run it afterward.Please do not only make changes to file src/json.hpp
-- please read the paragraph above and understand why src/json.hpp.re2c
exists.
The C++11 support varies between different compilers and versions. Please note the list of supported compilers. Some compilers like GCC 4.8 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support. Please refrain from proposing changes that work around these compiler's limitations with #ifdef
s or other means.
Specifically, I am aware of compilation problems with Microsoft Visual Studio (there even is an issue label for these kind of bugs). I understand that even in 2016, complete C++11 support isn‘t there yet. But please also understand that I do not want to drop features or uglify the code just to make Microsoft’s sub-standard compiler happy. The past has shown that there are ways to express the functionality such that the code compiles with the most recent MSVC - unfortunately, this is not the main objective of the project.
Please refrain from proposing changes that would break JSON conformance. If you propose a conformant extension of JSON to be supported by the library, please motivate this extension.
std::map
with std::less
is used by default.) Note this behavior conforms to the standard, and we shall not it to any other order.Please do not open pull requests that address multiple issues.
The following areas really need contribution:
json.hpp
header, and I am not aware of approaches similar to re2c
for parsing.