deploy: f7972970a4

community/contribution_guidelines/index.html

@@ -6,4 +6,4 @@ $<span class=w> </span>ctest<span class=w> </span>--test-dir<span class=w> </spa
 make<span class=w> </span>serve<span class=w> </span>-C<span class=w> </span>docs/mkdocs
 </code></pre></div> <p>The documentation will then be available at <a href="http://127.0.0.1:8000/">http://127.0.0.1:8000/</a>. See the documentation of <a href="https://www.mkdocs.org">mkdocs</a> and <a href="https://squidfunk.github.io/mkdocs-material/">Material for MkDocs</a> for more information.</p> <h3 id=amalgamate-the-source-code>Amalgamate the source code<a class=headerlink href=#amalgamate-the-source-code title="Permanent link">&para;</a></h3> <p>The single-header files <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp"><code>single_include/nlohmann/json.hpp</code></a> and <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp"><code>single_include/nlohmann/json_fwd.hpp</code></a> are <strong>generated</strong> from the source files in the <a href="https://github.com/nlohmann/json/tree/develop/include/nlohmann"><code>include/nlohmann</code> directory</a>. <strong>Do not</strong> edit the files directly; instead, modify the include/nlohmann sources and regenerate the files by executing:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>amalgamate
 </code></pre></div> <p>Running <code>make amalgamate</code> will also apply automatic formatting to the source files using <a href="https://astyle.sourceforge.net/"><code>Artistic Style</code></a>. This formatting may modify your source files in-place. Be certain to review and commit any changes to avoid unintended formatting diffs in commits.</p> <p>If you add, rename, or remove a header in <code>include/nlohmann</code>, also regenerate the header list in <a href="https://github.com/nlohmann/json/blob/develop/BUILD.bazel"><code>BUILD.bazel</code></a> (requires CMake) by executing:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>BUILD.bazel
-</code></pre></div> <p>The amalgamation check in <abbr title="Continuous Integration">CI</abbr> fails if any of these generated files is out of date.</p> <h2 id=recommended-documentation>Recommended documentation<a class=headerlink href=#recommended-documentation title="Permanent link">&para;</a></h2> <ul> <li>The library’s <a href="https://github.com/nlohmann/json/blob/master/README.md">README file</a> is an excellent starting point to understand its functionality.</li> <li>The <a href="https://json.nlohmann.me">documentation page</a> is the reference documentation of the library.</li> <li><a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> is the reference for the JavaScript Object Notation (<abbr title="JavaScript Object Notation">JSON</abbr>) Data Interchange Format.</li> </ul> <h2 id=please-dont>Please don't...<a class=headerlink href=#please-dont title="Permanent link">&para;</a></h2> <p>Certain contributions are not helpful.</p> <h3 id=break-the-public-api>Break the public <abbr title="Application Programming Interfaces">API</abbr><a class=headerlink href=#break-the-public-api title="Permanent link">&para;</a></h3> <p>We take pride in the library being used by <a href="https://json.nlohmann.me/home/customers/">numerous customers across various industries</a>. They all rely on the guarantees provided by <a href="https://semver.org">semantic versioning</a>. Please do not change the library such that the public <abbr title="Application Programming Interfaces">API</abbr> of the 3.x.y version is broken. This includes:</p> <ul> <li>Changing function signatures (altering parameter types, return types, number of parameters) or changing the const-ness of member functions.</li> <li>Removing functions.</li> <li>Renaming functions or classes.</li> <li>Changing exception handling.</li> <li>Changing exception ids.</li> <li>Changing access specifiers.</li> <li>Changing default arguments.</li> </ul> <p>Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.</p> <p>Breaking changes may be introduced when they are guarded with a feature macro such as <a href="https://json.nlohmann.me/api/macros/json_use_implicit_conversions/"><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.</p> <h3 id=break-c11-language-conformance>Break C++11 language conformance<a class=headerlink href=#break-c11-language-conformance title="Permanent link">&para;</a></h3> <p>This library is designed to work with C++11 and later. This means that any <a href="https://github.com/nlohmann/json/blob/master/README.md#supported-compilers">supported C++11 compiler</a> should compile the library without problems. Some compilers like <abbr title="GNU Compiler Collection">GCC</abbr> 4.7 (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.</p> <p>Please do not add features that do not work with the mentioned supported compilers. Please guard features from C++14 and later against the respective <a href="https://json.nlohmann.me/api/macros/json_has_cpp_11/"><code>JSON_HAS_CPP_14</code></a> macros.</p> <h3 id=break-json-conformance>Break <abbr title="JavaScript Object Notation">JSON</abbr> conformance<a class=headerlink href=#break-json-conformance title="Permanent link">&para;</a></h3> <p>Please refrain from proposing changes that would <strong>break <a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="JavaScript Object Notation">JSON</abbr></a> conformance</strong>. If you propose a conformant extension of <abbr title="JavaScript Object Notation">JSON</abbr> to be supported by the library, please motivate this extension.</p> <h2 id=wanted>Wanted<a class=headerlink href=#wanted title="Permanent link">&para;</a></h2> <p>The following areas really need contribution and are always welcomed:</p> <ul> <li>Extending the <strong>continuous integration</strong> toward more exotic compilers such as Android <abbr title="Native Development Kit">NDK</abbr>, Intel's Compiler, or the bleeding-edge versions Clang.</li> <li>Improving the efficiency of the <strong><abbr title="JavaScript Object Notation">JSON</abbr> parser</strong>. The current parser is implemented as a naive recursive descent parser with hand-coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the <code>json.hpp</code> header, and I am not aware of approaches similar to <a href="http://re2c.org"><code>re2c</code></a> for parsing.</li> <li>Extending and updating existing <strong>bencLine truncated
+</code></pre></div> <p>The amalgamation check in <abbr title="Continuous Integration">CI</abbr> fails if any of these generated files is out of date.</p> <h2 id=recommended-documentation>Recommended documentation<a class=headerlink href=#recommended-documentation title="Permanent link">&para;</a></h2> <ul> <li>The library’s <a href="https://github.com/nlohmann/json/blob/master/README.md">README file</a> is an excellent starting point to understand its functionality.</li> <li>The <a href="https://json.nlohmann.me">documentation page</a> is the reference documentation of the library.</li> <li><a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> is the reference for the JavaScript Object Notation (<abbr title="JavaScript Object Notation">JSON</abbr>) Data Interchange Format.</li> </ul> <h2 id=please-dont>Please don't...<a class=headerlink href=#please-dont title="Permanent link">&para;</a></h2> <p>Certain contributions are not helpful.</p> <h3 id=break-the-public-api>Break the public <abbr title="Application Programming Interfaces">API</abbr><a class=headerlink href=#break-the-public-api title="Permanent link">&para;</a></h3> <p>We take pride in the library being used by <a href="https://json.nlohmann.me/home/customers/">numerous customers across various industries</a>. They all rely on the guarantees provided by <a href="https://semver.org">semantic versioning</a>. Please do not change the library such that the public <abbr title="Application Programming Interfaces">API</abbr> of the 3.x.y version is broken. This includes:</p> <ul> <li>Changing function signatures (altering parameter types, return types, number of parameters) or changing the const-ness of member functions.</li> <li>Removing functions.</li> <li>Renaming functions or classes.</li> <li>Changing exception handling.</li> <li>Changing exception ids.</li> <li>Changing access specifiers.</li> <li>Changing default arguments.</li> </ul> <p>Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.</p> <p>Breaking changes may be introduced when they are guarded with a feature macro such as <a href="https://json.nlohmann.me/api/macros/json_use_implicit_conversions/"><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.</p> <h3 id=break-c11-language-conformance>Break C++11 language conformance<a class=headerlink href=#break-c11-language-conformance title="Permanent link">&para;</a></h3> <p>This library is designed to work with C++11 and later. This means that any <a href="https://github.com/nlohmann/json/blob/master/README.md#supported-compilers">supported C++11 compiler</a> should compile the library without problems. Some compilers like <abbr title="GNU Compiler Collection">GCC</abbr> 4.7 (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.</p> <p>Please do not add features that do not work with the mentioned supported compilers. Please guard features from C++14 and later against the respective <a href="https://json.nlohmann.me/api/macros/json_has_cpp_11/"><code>JSON_HAS_CPP_14</code></a> macros.</p> <h3 id=break-json-conformance>Break <abbr title="JavaScript Object Notation">JSON</abbr> conformance<a class=headerlink href=#break-json-conformance title="Permanent link">&para;</a></h3> <p>Please refrain from proposing changes that would <strong>break <a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="JavaScript Object Notation">JSON</abbr></a> conformance</strong>. If you propose a conformant extension of <abbr title="JavaScript Object Notation">JSON</abbr> to be supported by the library, please motivate this extension.</p> <h2 id=wanted>Wanted<a class=headerlink href=#wanted title="Permanent link">&para;</a></h2> <p>The following areas really need contribution and are always welcomed:</p> <ul> <li>Extending the <strong>continuous integration</strong> toward more exotic compilers such as Android <abbr title="Native Development Kit">NDK</abbr>, Intel's Compiler, or the bleeding-edge versions Clang.</li> <li>Improving the efficiency of the <strong><abbr title="JavaScript Object Notation">JSON</abbr> parser</strong>. The current parser is implemented as a naive recursive descent parser with hand-coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the <code>json.hpp</code> header, and I am not aware of approaches similar to <a href="http://re2c.org"><code>re2c</code></a> for parsing.</li> <li>Extending and updating existing <strong>bencLine truncated