|
1 | | -The simdjson library is an open project written in C++. Contributions are invited. Contributors agree to the project's license. |
| 1 | +Contributing |
| 2 | +============ |
2 | 3 |
|
3 | | -We have an extensive list of issues, and contributions toward any of these issues is invited. Contributions can take the form of code samples, better documentation or design ideas. |
| 4 | +The simdjson library is an open project written in C++. Contributions are invited. Contributors |
| 5 | +agree to the project's license. |
| 6 | + |
| 7 | +We have an extensive list of issues, and contributions toward any of these issues is invited. |
| 8 | +Contributions can take the form of code samples, better documentation or design ideas. |
4 | 9 |
|
5 | 10 | In particular, the following contributions are invited: |
6 | 11 |
|
7 | 12 | - The library is focused on performance. Well-documented performance optimization are invited. |
8 | | -- Fixes to known or newly discovered bugs are always welcome. Typically, a bug fix should come with a test demonstrating that the bug has been fixed. |
9 | | -- The simdjson library is advanced software and maintainability and flexibility are always a concern. Specific contributions to improve maintainability and flexibility are invited. |
10 | | - |
11 | | - |
| 13 | +- Fixes to known or newly discovered bugs are always welcome. Typically, a bug fix should come with |
| 14 | + a test demonstrating that the bug has been fixed. |
| 15 | +- The simdjson library is advanced software and maintainability and flexibility are always a |
| 16 | + concern. Specific contributions to improve maintainability and flexibility are invited. |
12 | 17 |
|
13 | 18 | We discourage the following types of contributions: |
14 | 19 |
|
15 | | -- Code refactoring. We all have our preferences as to how code should be written, but unnecessary refactoring can waste time and introduce new bugs. If you believe that refactoring is needed, you first must explain how it helps in concrete terms. Does it improve the performance? |
16 | | -- Applications of new language features for their own sake. Using advanced C++ language constructs is actually a negative as it may reduce portability (to old compilers, old standard libraries and systems) and reduce accessibility (to programmers that have not kept up), so it must be offsetted by clear gains like performance or maintainability. When in doubt, avoid advanced C++ features (beyond C++11). |
17 | | -- Style formatting. In general, please abstain from reformatting code just to make it look prettier. Though code formatting is important, it can also be a waste of time if several contributors try to tweak the code base toward their own preference. Please do not introduce unneeded white-space changes. |
| 20 | +- Code refactoring. We all have our preferences as to how code should be written, but unnecessary |
| 21 | + refactoring can waste time and introduce new bugs. If you believe that refactoring is needed, you |
| 22 | + first must explain how it helps in concrete terms. Does it improve the performance? |
| 23 | +- Applications of new language features for their own sake. Using advanced C++ language constructs |
| 24 | + is actually a negative as it may reduce portability (to old compilers, old standard libraries and |
| 25 | + systems) and reduce accessibility (to programmers that have not kept up), so it must be offsetted |
| 26 | + by clear gains like performance or maintainability. When in doubt, avoid advanced C++ features |
| 27 | + (beyond C++11). |
| 28 | +- Style formatting. In general, please abstain from reformatting code just to make it look prettier. |
| 29 | + Though code formatting is important, it can also be a waste of time if several contributors try to |
| 30 | + tweak the code base toward their own preference. Please do not introduce unneeded white-space |
| 31 | + changes. |
18 | 32 |
|
19 | 33 | In short, most code changes should either bring new features or better performance. We want to avoid unmotivated code changes. |
20 | 34 |
|
21 | | -Contributors are encouraged to |
| 35 | +Guidelines |
| 36 | +---------- |
| 37 | + |
| 38 | +Contributors are encouraged to : |
22 | 39 |
|
23 | 40 | - Document their changes. Though we do not enforce a rule regarding code comments, we prefer that non-trivial algorithms and techniques be somewhat documented in the code. |
24 | 41 | - Follow as much as possible the existing code style. We do not enforce a specific code style, but we prefer consistency. |
25 | 42 | - Modify as few lines of code as possible when working on an issue. The more lines you modify, the harder it is for your fellow human beings to understand what is going on. |
26 | 43 | - Tools may report "problems" with the code, but we never delegate programming to tools: if there is a problem with the code, we need to understand it. Thus we will not "fix" code merely to please a static analyzer if we do not understand. |
27 | 44 | - Provide tests for any new feature. We will not merge a new feature without tests. |
28 | 45 |
|
| 46 | +Code of Conduct |
| 47 | +--------------- |
29 | 48 |
|
| 49 | +Though we do not have a formal code of conduct, we will not tolerate bullying, bigotry or |
| 50 | +intimidation. Everyone is welcome to contribute. |
30 | 51 |
|
31 | | -Though we do not have a formal code of conduct, we will not tolerate bullying, bigotry or intimidation. Everyone is welcome to contribute. |
| 52 | +Getting Started Hacking |
| 53 | +----------------------- |
32 | 54 |
|
| 55 | +An overview of simdjson's directory structure, with pointers to architecture and design |
| 56 | +considerations and other helpful notes, can be found at [HACKING.md](HACKING.md). |
0 commit comments