mirror of
https://github.com/nlohmann/json.git
synced 2026-07-29 15:13:04 +04:00
Clean up and document project files (#4560)
This commit is contained in:
Niels Lohmann
GitHub
@@ -0,0 +1 @@
|
||||
--8<-- "../../../.github/CODE_OF_CONDUCT.md"
|
||||
@@ -0,0 +1 @@
|
||||
--8<-- "../../../.github/CONTRIBUTING.md"
|
||||
@@ -0,0 +1,122 @@
|
||||
# Governance
|
||||
|
||||
The governance model for the JSON for Modern C++ project is a **Benevolent Dictator for Life (BDFL)** structure. As the
|
||||
sole maintainer, [Niels Lohmann](https://github.com/nlohmann) is responsible for all key aspects of the project. The
|
||||
project governance may evolve as the project grows, but any changes will be documented here and communicated to
|
||||
contributors.
|
||||
|
||||
## Overview
|
||||
|
||||
This project is led by a benevolent dictator, [Niels Lohmann](https://github.com/nlohmann), and managed by the
|
||||
community. That is, the community actively contributes to the day-to-day maintenance of the project, but the general
|
||||
strategic line is drawn by the benevolent dictator. In case of disagreement, they have the last word. It is the
|
||||
benevolent dictator’s job to resolve disputes within the community and to ensure that the project is able to progress in
|
||||
a coordinated way. In turn, it is the community’s job to guide the decisions of the benevolent dictator through active
|
||||
engagement and contribution.
|
||||
|
||||
## Roles and responsibilities
|
||||
|
||||
### Benevolent dictator (project lead)
|
||||
|
||||
Typically, the benevolent dictator, or project lead, is self-appointed. However, because the community always has the
|
||||
ability to fork, this person is fully answerable to the community. The project lead’s role is a difficult one: they set
|
||||
the strategic objectives of the project and communicate these clearly to the community. They also have to understand the
|
||||
community as a whole and strive to satisfy as many conflicting needs as possible, while ensuring that the project
|
||||
survives in the long term.
|
||||
|
||||
In many ways, the role of the benevolent dictator is less about dictatorship and more about diplomacy. The key is to
|
||||
ensure that, as the project expands, the right people are given influence over it and the community rallies behind the
|
||||
vision of the project lead. The lead’s job is then to ensure that the committers (see below) make the right decisions on
|
||||
behalf of the project. Generally speaking, as long as the committers are aligned with the project’s strategy, the
|
||||
project lead will allow them to proceed as they desire.
|
||||
|
||||
### Committers
|
||||
|
||||
Committers are contributors who have made several valuable contributions to the project and are now relied upon to both
|
||||
write code directly to the repository and screen the contributions of others. In many cases they are programmers but it
|
||||
is also possible that they contribute in a different role. Typically, a committer will focus on a specific aspect of the
|
||||
project, and will bring a level of expertise and understanding that earns them the respect of the community and the
|
||||
project lead. The role of committer is not an official one, it is simply a position that influential members of the
|
||||
community will find themselves in as the project lead looks to them for guidance and support.
|
||||
|
||||
Committers have no authority over the overall direction of the project. However, they do have the ear of the project
|
||||
lead. It is a committer’s job to ensure that the lead is aware of the community’s needs and collective objectives, and
|
||||
to help develop or elicit appropriate contributions to the project. Often, committers are given informal control over
|
||||
their specific areas of responsibility, and are assigned rights to directly modify certain areas of the source code.
|
||||
That is, although committers do not have explicit decision-making authority, they will often find that their actions are
|
||||
synonymous with the decisions made by the lead.
|
||||
|
||||
### Contributors
|
||||
|
||||
Contributors are community members who either have no desire to become committers, or have not yet been given the
|
||||
opportunity by the benevolent dictator. They make valuable contributions, such as those outlined in the list below, but
|
||||
generally do not have the authority to make direct changes to the project code. Contributors engage with the project
|
||||
through communication tools, such as email lists, and via reports and patches attached to issues in the issue tracker,
|
||||
as detailed in our community tools document.
|
||||
|
||||
Anyone can become a contributor. There is no expectation of commitment to the project, no specific skill requirements
|
||||
and no selection process. To become a contributor, a community member simply has to perform one or more actions that are
|
||||
beneficial to the project.
|
||||
|
||||
Some contributors will already be engaging with the project as users, but will also find themselves doing one or more of
|
||||
the following:
|
||||
|
||||
- supporting new users (current users often provide the most effective new user support)
|
||||
- reporting bugs
|
||||
- identifying requirements
|
||||
- supplying graphics and web design
|
||||
- programming
|
||||
- assisting with project infrastructure
|
||||
- writing documentation
|
||||
- fixing bugs
|
||||
- adding features
|
||||
|
||||
As contributors gain experience and familiarity with the project, they may find that the project lead starts relying on
|
||||
them more and more. When this begins to happen, they gradually adopt the role of committer, as described above.
|
||||
|
||||
### Users
|
||||
|
||||
Users are community members who have a need for the project. They are the most important members of the community:
|
||||
without them, the project would have no purpose. Anyone can be a user; there are no specific requirements.
|
||||
|
||||
Users should be encouraged to participate in the life of the project and the community as much as possible. User
|
||||
contributions enable the project team to ensure that they are satisfying the needs of those users. Common user
|
||||
activities include (but are not limited to):
|
||||
|
||||
- evangelising about the project
|
||||
- informing developers of project strengths and weaknesses from a new user’s perspective
|
||||
- providing moral support (a ‘thank you’ goes a long way)
|
||||
- providing financial support
|
||||
|
||||
Users who continue to engage with the project and its community will often find themselves becoming more and more
|
||||
involved. Such users may then go on to become contributors, as described above.
|
||||
|
||||
## Support
|
||||
|
||||
All participants in the community are encouraged to provide support for new users within the project management
|
||||
infrastructure. This support is provided as a way of growing the community. Those seeking support should recognise that
|
||||
all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring
|
||||
guaranteed response times or results should therefore seek to purchase a support contract from a vendor. (Of course,
|
||||
that vendor should be an active member of the community.) However, for those willing to engage with the project on its
|
||||
own terms, and willing to help support other users, the community support channels are ideal.
|
||||
|
||||
## Contribution Process
|
||||
|
||||
Anyone can contribute to the project, regardless of their skills, as there are many ways to contribute. For instance, a
|
||||
contributor might be active on the project mailing list and issue tracker, or might supply patches. The various ways of
|
||||
contributing are described in more detail in our roles in open source document.
|
||||
|
||||
The developer mailing list is the most appropriate place for a contributor to ask for help when making their first
|
||||
contribution.
|
||||
|
||||
## Decision-Making Process
|
||||
|
||||
The benevolent dictatorship model does not need a formal conflict resolution process, since the project lead’s word is
|
||||
final. If the community chooses to question the wisdom of the actions of a committer, the project lead can review their
|
||||
decisions by checking the email archives, and either uphold or reverse them.
|
||||
|
||||
---
|
||||
|
||||
!!! quote "Source"
|
||||
|
||||
The text was taken from http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel.
|
||||
@@ -0,0 +1,7 @@
|
||||
# Community
|
||||
|
||||
- [Code of Conduct](code_of_conduct.md) - the rules and norms of this project
|
||||
- [Contribution Guidelines](contribution_guidelines.md) - guidelines how to contribute to this project
|
||||
- [Governance](governance.md) - the governance model of this project
|
||||
- [Quality Assurance](quality_assurance.md) - how quality of this project is assured
|
||||
- [Security Policy](security_policy.md) - the security policy of the project
|
||||
@@ -0,0 +1,210 @@
|
||||
# Quality assurance
|
||||
|
||||
Ensuring quality is paramount for this project, particularly because [numerous other projects](../home/customers.md)
|
||||
depend on it. Each commit to the library undergoes rigorous checks against the following requirements, and any
|
||||
violations will result in a failed build.
|
||||
|
||||
## C++ language compliance and compiler compatibility
|
||||
|
||||
!!! success "Requirement: Compiler support"
|
||||
|
||||
Any compiler with complete C++11 support can compile the library without warnings.
|
||||
|
||||
- [x] The library is compiled library with 50+ different C++ compilers with different operating systems and platforms,
|
||||
including the oldest versions known to compile the library.
|
||||
|
||||
??? abstract "Compilers used in continuous integration"
|
||||
|
||||
| Compiler | Architecture | Operating System | CI |
|
||||
|----------------------------------------------|--------------|--------------------------|-----------|
|
||||
| AppleClang 14.0.0.14000029; Xcode 14.1 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
|
||||
| AppleClang 14.0.0.14000029; Xcode 14.2 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
|
||||
| AppleClang 14.0.3.14030022; Xcode 14.3.1 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
|
||||
| AppleClang 15.0.0.15000040; Xcode 15.0.1 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
|
||||
| AppleClang 15.0.0.15000100; Xcode 15.1 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
|
||||
| AppleClang 15.0.0.15000100; Xcode 15.2 | x86_64 | macOS 13.7.2 (Ventura) | GitHub |
|
||||
| AppleClang 15.0.0.15000309; Xcode 15.3 | arm64 | macOS 14.7.2 (Sonoma) | GitHub |
|
||||
| AppleClang 15.0.0.15000309; Xcode 15.4 | arm64 | macOS 14.7.2 (Sonoma) | GitHub |
|
||||
| AppleClang 16.0.0.16000026; Xcode 16 | arm64 | macOS 15.2 (Sequoia) | GitHub |
|
||||
| AppleClang 16.0.0.16000026; Xcode 16.1 | arm64 | macOS 15.2 (Sequoia) | GitHub |
|
||||
| AppleClang 16.0.0.16000026; Xcode 16.2 | arm64 | macOS 15.2 (Sequoia) | GitHub |
|
||||
| Clang 3.5.2 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 3.6.2 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 3.7.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 3.8.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 3.9.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 4.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 5.0.2 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 6.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 7.1.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 8.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 9.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 10.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 11.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
|
||||
| Clang 11.1.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 12.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
|
||||
| Clang 12.0.0 with MSVC-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
|
||||
| Clang 12.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 13.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
|
||||
| Clang 13.0.1 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 14.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
|
||||
| Clang 14.0.6 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 15.0.0 with GNU-like command-line | x86_64 | Windows 10 (Build 17763) | GitHub |
|
||||
| Clang 15.0.7 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 16.0.6 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 17.0.6 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 18.1.8 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 19.1.6 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| Clang 20.0.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 4.8.5 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 4.9.3 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 5.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 6.4.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 7.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 8.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 9.3.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 9.4.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 9.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 10.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 11.4.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 11.5.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 12.2.0 (MinGW-W64 i686-ucrt-posix-dwarf) | x86_64 | Windows 10 (Build 17763) | GitHub |
|
||||
| GNU 12.2.0 (MinGW-W64 x86_64-ucrt-posix-seh) | x86_64 | Windows 10 (Build 17763) | GitHub |
|
||||
| GNU 12.4.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 13.3.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 14.2.0 | x86_64 | Ubuntu 22.04.1 LTS | GitHub |
|
||||
| GNU 14.2.0 | arm64 | Linux 6.1.100 | Cirrus CI |
|
||||
| MSVC 19.0.24241.7 | x86 | Windows 8.1 | AppVeyor |
|
||||
| MSVC 19.16.27035.0 | x86 | Windows-10 (Build 14393) | AppVeyor |
|
||||
| MSVC 19.29.30157.0 | x86 | Windows 10 (Build 17763) | GitHub |
|
||||
| MSVC 19.29.30157.0 | x86_64 | Windows 10 (Build 17763) | GitHub |
|
||||
| MSVC 19.29.30157.0 | x86 | Windows-10 (Build 17763) | AppVeyor |
|
||||
| MSVC 19.42.34435.0 | x86 | Windows 10 (Build 20348) | GitHub |
|
||||
| MSVC 19.42.34435.0 | x86_64 | Windows 10 (Build 20348) | GitHub |
|
||||
|
||||
- [x] The library is compiled with all C++ language revisions (C++11, C++14, C++17, C++20, C++23, and C++26) to detect
|
||||
and fix language deprecations early.
|
||||
- [x] The library is checked for compiler warnings:
|
||||
- On Clang, `-Weverything` is used with 7 exceptions.
|
||||
|
||||
??? abstract "Clang warnings"
|
||||
|
||||
```cmake
|
||||
--8<-- "../../../cmake/clang_flags.cmake"
|
||||
```
|
||||
|
||||
- On GCC, 300+ warnings are enabled with 8 exceptions.
|
||||
|
||||
??? abstract "GCC warnings"
|
||||
|
||||
```cmake
|
||||
--8<-- "../../../cmake/gcc_flags.cmake"
|
||||
```
|
||||
|
||||
## C++ standard library compliance
|
||||
|
||||
!!! success "Requirement: No prerequisites"
|
||||
|
||||
The library has no prerequisites other than the Standard Template Library (STL).
|
||||
|
||||
- [x] The library compiled and tested with both [libc++](https://libcxx.llvm.org) and
|
||||
[libstdc++](https://gcc.gnu.org/onlinedocs/libstdc++/) to detect subtle differences or incompatibilities.
|
||||
- [x] The code checked with [Include What You Use (IWYU)](https://include-what-you-use.org) that all required standard
|
||||
headers are included.
|
||||
- [x] On Windows, the library is compiled with `<Windows.h>` being included to detect and avoid common bugs.
|
||||
- [x] The library is compiled with exceptions disabled to support alternative means of error handling.
|
||||
|
||||
## Stable public API
|
||||
|
||||
!!! success "Requirement: Stable public API"
|
||||
|
||||
Any change to the library does not break the public API.
|
||||
|
||||
- [x] All public API functions are tested with a variety of arguments.
|
||||
- [x] The library is compiled and tested with different template arguments for number, string, array, and object types.
|
||||
- [x] All lines of the code base are covered by unit tests.
|
||||
- [x] Every exception of the library is thrown in the test suite and the error messages and exception ids are checked.
|
||||
|
||||
!!! success "Requirement: Complete documentation"
|
||||
|
||||
The public API is extensively documented.
|
||||
|
||||
- [x] Every public API function has a dedicated page in the
|
||||
[API reference documentation](https://json.nlohmann.me/api/basic_json/) with a self-contained code example.
|
||||
- [x] All examples in the documentation are tested and changes in their output is treated as an error.
|
||||
|
||||
## Robust input processing
|
||||
|
||||
!!! success "Requirement: Standards compliance"
|
||||
|
||||
The library is compliant to JSON as defined in [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259).
|
||||
|
||||
- [x] The lexer is tested with all valid Unicode code points and all prefixes of all invalid Unicode code points.
|
||||
- [x] The parser is tested against extensive correctness suites for JSON compliance.
|
||||
- [x] In addition, the library is continuously fuzz-tested at [OSS-Fuzz](https://google.github.io/oss-fuzz/) where the
|
||||
library is checked against billions of inputs.
|
||||
|
||||
## Static analysis
|
||||
|
||||
!!! success "Requirement: State-of-the-art code analysis"
|
||||
|
||||
The code is checked with state-of-the-art static code analysis tools.
|
||||
|
||||
- [x] The code is checked with the latest [Clang-Tidy](https://clang.llvm.org/extra/clang-tidy/).
|
||||
|
||||
??? abstract "Clang-Tidy configuration (.clang-tidy)"
|
||||
|
||||
```ini
|
||||
--8<-- "../../../.clang-tidy"
|
||||
```
|
||||
|
||||
- [x] The code is checked with the latest [Cppcheck](https://cppcheck.sourceforge.io) with all warnings enabled.
|
||||
- [x] The code is checked with the latest [Clang Static Analyzer](https://clang-analyzer.llvm.org) with 89 enabled
|
||||
rules.
|
||||
- [x] The code is checked with [Infer](https://fbinfer.com).
|
||||
- [x] The code is checked with [Codacy](https://app.codacy.com/gh/nlohmann/json/dashboard).
|
||||
|
||||
## Dynamic analysis
|
||||
|
||||
!!! success "Requirement: Correctness"
|
||||
|
||||
The library is checked for memory correctness and absence of undefined behavior.
|
||||
|
||||
- [x] The test suite is executed with enabled [runtime assertions](https://json.nlohmann.me/features/assertions/) to
|
||||
check invariants and preconditions of functions to detect undefined behavior.
|
||||
- [x] The test suite is executed with [Valgrind](https://valgrind.org) (Memcheck) to detect memory leaks.
|
||||
- [x] The test suite is executed with [Sanitizers](https://github.com/google/sanitizers) (address sanitizer, undefined
|
||||
behavior sanitizer, integer overflow detection, nullability violations).
|
||||
|
||||
## Style check
|
||||
|
||||
!!! success "Requirement: Common code style"
|
||||
|
||||
A common code style is used throughout all code files of the library.
|
||||
|
||||
- [x] The code is formatted with [Artistic Style](https://astyle.sourceforge.net) (astyle) against a style configuration
|
||||
that is also enforced in the CI.
|
||||
|
||||
??? abstract "Astyle configuration (tools/astyle/.astylerc)"
|
||||
|
||||
```ini
|
||||
--8<-- "../../../tools/astyle/.astylerc"
|
||||
```
|
||||
|
||||
- [x] The code style is checked with [cpplint](https://github.com/cpplint/cpplint) with 61 enabled rules.
|
||||
|
||||
## Simple integration
|
||||
|
||||
!!! success "Requirement: Single header"
|
||||
|
||||
The library can be used by adding a single header to a C++ project.
|
||||
|
||||
- [x] An amalgamation script is used to check if the source code is exposed as self-contained single-header file.
|
||||
- [x] The test suite is checked against the amalgamated source file as well as the individual source file.
|
||||
|
||||
!!! success "Requirement: CMake as primary development tool"
|
||||
|
||||
All library functions are exposed and usable by CMake.
|
||||
|
||||
- [x] All library options are exposed as [CMake options](https://json.nlohmann.me/integration/cmake/) and tested.
|
||||
- [x] The library is tested against the earliest supported CMake version.
|
||||
@@ -0,0 +1 @@
|
||||
--8<-- "../../../.github/SECURITY.md"
|
||||
Reference in New Issue
Block a user