Skip to content

Latest commit

 

History

History
160 lines (114 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

160 lines (114 loc) · 10.7 KB
Raw

How to contribute

Thank you for visiting the fkYAML project. If you make any contribution for this project, it will surely be some help for us and other users in the future.

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 itself is subject to discussion, so please create a discussion or a pull request if you find a way to improve it!

Private reports

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 published), please send an email to fktn.dev@gmail.com.

Describe your request/issue

Please create a discussion or issue, assuming one does not already exist, and describe your concern.
Note you need a GitHub account for this.

Please keep in mind the followings:

  • If you propose a change or addition, try to give an example how the improved code could look like or how to use it.
  • If you find a bug, please describe how to reproduce it. If possible, attach a complete example which demonstrates the error. Please also state what you expected to happen instead of the error.
  • If you find a compilation error, please tell us which compiler (version and operating system) you used and paste the (relevant part of) the error messages to the ticket.

For questions, feature or support requests, please open a discussion.

Contribution Steps

Basically, follow the contribution guideline in the GitHub Docs.
To make changes to the fkYAML project, you need to edit the following files:

1. include/fkYAML/**.hpp

These files are the sources of the fkYAML library and DO NOT directly change the single header version under the single_include directory. Alghough amalgamation is automatically executed in the GitHub Actions workflows, you can run the script (run_amalgamation.bat for Windows, run_amalgamation.sh otherwise) to regenerate single_include/fkYAML/node.hpp locally, which will save you from waiting unnecessarily long for the workflow results.

Windows (Command Prompt)

cd path\to\fkYAML
scripts\run_amalgamation.bat

Otherwise

cd path/to/fkYAML
scripts/run_amalgamation.sh

If you just want to check if amalgamation is needed locally, run the script (run_amalgamation.bat for Windows, run_amalgamation.sh otherwise) with the following commands:

Windows (Command Prompt)

cd path\to\fkYAML
scripts\check_amalgamation.bat

Otherwise

cd path/to/fkYAML
scripts/check_amalgamation.sh

2. test/unit_test/*.cpp

These files contain the Catch2 unit tests from which current coverage data is generated. (Click here to see the current coverage of the library's code.) If you have added or changed a feature, please also modify a unit test to the associated file(s) to keep covering 100% of the lines/branches in the fkYAML library.

The unit tests can be compiled and executed with the following commands:

cd path/to/fkYAML
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug -DFK_YAML_BUILD_TEST=ON [-DFK_YAML_USE_SINGLE_HEADER=(ON|OFF)]
cmake --build build --config Debug
ctest -C Debug --test-dir build --output-on-failure

Furthermore, you can test the single-header version of fkYAML by passing -DFK_YAML_USE_SINGLE_HEADER=ON when you configure CMake. (disabled by default)

Check the coverage locally

In the GitHub Action workflows, test coverage information is generated with the LCOV tool.
The same file as uploaded to the Coveralls and its HTML version (generated by genhtml) can be downloaded from the link in the autogenerated message from the bot per push event.

You might want to check the coverage locally before creating a PR, for example, to ensure that the coverage remains still after you change the library sources.
In such cases, please run the following commands and open a generated index.html file in the <repo_root>/build_coverage/html directory to check the result.
Make sure lcov and genhtml commands are available before execution.

cd /path/to/fkYAML
make html-coverage
For Windows users (help needed)

I currently don't know the way in which the dependent commands, lcov and genhtml, are run on the "pure" Windows platform, neither using WSL2 nor Cygwin.
Until such a way is found, I recommend you use WSL2 or other similar means where you can run a Linux environment on Windows.
If you have an idea to run those tools on the "pure" Windows platform, please open a discussion or a PR to share it with the other Windows users.

3. docs/mkdocs/docs/**.md

These files are the sources of the documentation from which MkDocs generates the documentation. If you have added or changed a feature, please also add sufficient descriptions so that the documentation is kept up-to-date.

Also, you can build & check the updated documentation on your local environment by executing the following commands:

cd path/to/fkYAML
make -C docs/mkdocs serve

The commands above will automatically install all the dependencies using Python venv with the requirements.txt file. The generated documentation will be available by accessing http://127.0.0.1:8000/.

4. Format source files

GitHub Actions will test the updated project with the Clang-Format tool (18.1.3) once you open a PR or push commits afterwards which include changes in the source files under either include or test directories.
Although code formatting is automatically executed in the GitHub Actions workflows, you can run the script files (run_clang_format.bat for Windows, run_clang_format.sh otherwise) to check if your changes follow the rules defined in the .clang-format file on your local environment in advance.
Note that, since the Clang-Format tool does not gurantee backward compatibility especially in its edge cases and its behaviors might therefore vary from version to version, it's highly recommended that you use the above script files to avoid unnecessary confusion for that kind of reason.
The scripts uses the Clang-Format Python distribution and installs it using the Python venv module if it's not been installed yet.
You can run the scripts with the following commands:

Windows (Command Prompt)

cd path\to\fkYAML
scripts\run_clang_format.bat

Otherwise

cd path/to/fkYAML
scripts/run_clang_format.sh

Note

When you open a pull request, fkYAML will automatically be built/tested with (1) various combinations of compilers and operating systems and (2) analyzers such as Valgrind and Clang Sanitizers to detect runtime issues (e.g., memory leaks), on GitHub Actions once you open a pull request.
These can result in failing builds and/or unit tests which run successfully on your local environment.
As a policy of this project, however, all the workflow checks must be passed before merging.
You can run tests with those tools with the following commands:

Valgrind (assuming Valgrind is already installed.)

cd path/to/fkYAML
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug -DFK_YAML_BUOLD_TEST=ON -DFK_YAML_RUN_VALGRIND=ON
cmake --build build --config Debug
ctest -C Debug -T memcheck --test-dir build --output-on-failure

Clang Sanitizers (assuming some version of Clang is already installed.)

cd path/to/fkYAML
CXX=clang++ cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug -DFK_YAML_BUILD_TEST=ON -DFK_YAML_RUN_CLANG_SANITIZERS=ON
cmake --build build --config Debug
ctest -C Debug --test-dir build --output-on-failure

Please don't

  • The C++11 support varies between different compilers and versions. Please note the list of supported compilers. Some compilers like GCC 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. Please refrain from proposing changes that work around these compiler's limitations with #ifdefs or other means.
  • Please refrain from proposing changes that would break YAML specifications. If you propose a conformant extension of YAML to be supported by the library, please motivate this extension.
  • Please do not open pull requests that address multiple issues.

Help Wanted

The following areas really need contribution:

  • Extending the continuous integration to support more compilers, platforms, package managers, and/or operating systems, such as Android NDK, Intel's Compiler, or 32bit operating systems.
  • Introducing benchmarks to measure the processing cost of this library. Though efficiency is not everything, speed and memory consumption are very important characteristics for C++ developers. So, having proper comparisons would be reasonable for both contributors and users.