Merge pull request #231 from fktn-k/feature/improve_contribution_guide

Improved contribution guide

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+[Describe your pull request here. Please read the description below and make sure you follow the checklist.]  
+
+---
+
+## Pull Request Checklist
+
+Read the [CONTRIBUTING.md](https://github.com/fktn-k/fkYAML/blob/develop/CONTRIBUTING.md) file for detailed information.  
+
+- [ ] Changes are described in the pull request or in a referenced [issue](https://github.com/fktn-k/fkYAML/issues).
+- [ ] The test suite compiles and runs without any error.
+- [ ] [The code coverage](https://coveralls.io/github/fktn-k/fkYAML) on your branch is 100%.
+- [ ] The documentation is updated if you added/changed a feature.
+
+## Please don't
+
+- The C++11 support varies between different **compilers** and versions. Please note the [list of supported compilers](https://github.com/fktn-k/fkYAML/blob/develop/README.md#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 `#ifdef`s or other means.
+- Please refrain from proposing changes that would **break [YAML](https://yaml.org/) 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**.

CONTRIBUTING.md

@@ -1,8 +1,8 @@
 # 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 other users in the future.  
+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 is subject to discussion, so please [create a discussion](https://github.com/fktn-k/fkYAML/discussions) or a pull request if you find a way to improve it!
+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](https://github.com/fktn-k/fkYAML/discussions) or a pull request if you find a way to improve it!
 
 ## Private reports
 
@@ -23,27 +23,50 @@ Clearly describe the request/issue:
 
 For questions, feature or support requests, please [open a discussion](https://github.com/fktn-k/fkYAML/discussions/new).  
 
-## Files to change
+## Contribution Steps
 
-To make changes, you need to edit the following files:
+Basically, follow [the contribution guideline](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) on the GitHub Docs.  
+To make changes to the fkYAML project, you need to edit the following files:
 
-1. [`include/fkYAML/*.hpp`](https://github.com/fktn-k/fkYAML/tree/develop/include/fkYAML) - These files are the sources of the fkYAML library.
+1. [`include/fkYAML/**.hpp`](https://github.com/fktn-k/fkYAML/tree/develop/include/fkYAML) - These files are the sources of the fkYAML library.
 
-2. [`test/unit_test/*.cpp`](https://github.com/fktn-k/fkYAML/tree/develop/test/unit_test) - These files contain the [Catch2](https://github.com/catchorg/Catch2) unit tests from which current coverage data is generated. (Click [here](https://coveralls.io/github/fktn-k/fkYAML) to see current coverage of the library's code.)
+2. [`test/unit_test/*.cpp`](https://github.com/fktn-k/fkYAML/tree/develop/test/unit_test) - These files contain the [Catch2](https://github.com/catchorg/Catch2) unit tests from which current coverage data is generated. (Click [here](https://coveralls.io/github/fktn-k/fkYAML) to see the current coverage of the library's code.)
+
+3. [`docs/mkdocs/docs/**.md`](https://github.com/fktn-k/fkYAML/tree/develop/docs/mkdocs/docs) - These files are the sources of the documentation from which [MkDocs](https://www.mkdocs.org/) generates the documentation.  
+
+If you have added or changed a feature, please also add a unit test to the associated file(s) to keep covering 100% of the lines/branches in the fkYAML library, and add/modify sufficient descriptions to keep the documentation to be up-to-date as well.  
 
-If you add or change a feature, please also add 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:
 
-```sh
-$ mkdir build
-$ cd build
-$ cmake .. -DFK_YAML_BUILD_TEST=ON
-$ cmake --build .
-$ ctest
+```bash
+$ cd path/to/fkYAML
+$ cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug -DFK_YAML_BUILD_TEST=ON
+$ cmake --build build --config Debug
+$ ctest -C Debug --test-dir build --output-on-failure
 ```
 
 The test cases are also executed with various combinations of compilers and operating systems on [GitHub Actions](https://github.com/fktn-k/fkYAML/actions) once you open a pull request.  
-As the policy of this project, all the workflow checks must be passed before merging.
+As the policy of this project, all the workflow checks must be passed before merging.  
+
+Also, you can build & check the updated documentation on your local environment by executing the following commands:
+
+```bash
+$ cd path/to/fkYAML
+$ make -C docs/mkdocs serve
+```
+
+The commands above will automatically install all the dependencies using [Python venv](https://docs.python.org/3.10/library/venv.html) with the [`requirements.txt`](https://github.com/fktn-k/fkYAML/blob/develop/docs/mkdocs/requirements.txt) file. The generated documentation will be available by accessing http://127.0.0.1:8000/.
+
+## Before Opening a PR
+
+[GitHub Actions](https://github.com/fktn-k/fkYAML/actions) will test the updated project with the following Clang tools with the specific versions listed down below once you open a PR for your changes. So, it would be more efficient to check if your changes follow the predefined rules on your local environment in advance.  
+
+| Clang Tool Name                                                                                   | Version |
+| ------------------------------------------------------------------------------------------------- | ------- |
+| [Clang-Format](https://releases.llvm.org/14.0.0/tools/clang/docs/ClangFormat.html)                | 14.0.0  |
+| [Clang-Tidy](https://releases.llvm.org/14.0.0/tools/clang/tools/extra/docs/clang-tidy/index.html) | 14.0.0  |
+
+Those Clang tools, however, do not seem to gurantee backward compatibility and their behaviours vary from version to version. So, it is highly recommended to use the specific versions listed above to avoid unnecessary confusion.  
 
 ## Note
 
@@ -61,4 +84,4 @@ This can result in failing unit tests which run successfully without those tools
 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.
+- 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.

README.md

@@ -44,7 +44,7 @@ More detailed, exclusive descriptions with example usages for each fkYAML API ar
 ### :mag: **Heavily Tested**  
 fkYAML has been [unit-tested](https://github.com/fktn-k/fkYAML/tree/develop/test/unit_test) and its test suite covers 100% of lines and conditions of the codebase. (You can see the actual coverage [here](https://coveralls.io/github/fktn-k/fkYAML?branch=develop).)  
 We check with [Valgrind](https://valgrind.org) and the [Clang Sanitizers](https://clang.llvm.org/docs/index.html) that there are no runtime issues such as memory leak.  
-Furthermore, the quality of our codebase has been checked with [Clang-Tidy](https://clang.llvm.org/extra/clang-tidy/) and [CodeQL](https://codeql.github.com/docs/).  
+Furthermore, the quality of our codebase has been checked with [Clang-Tidy](https://releases.llvm.org/14.0.0/tools/clang/tools/extra/docs/clang-tidy/index.html) and [CodeQL](https://codeql.github.com/docs/).  
 [GitHub Actions](https://docs.github.com/en/actions) workflows run against every commit pushed on the main & develop branches to ensure that the fkYAML library can be successfully built/tested with a variety of compilers and C++ standards.  
 See the [supported compilers](#supported-compilers) section for more details.
 
@@ -152,13 +152,18 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE  
 SOFTWARE.  
 
+## How to contribute
+
+See the [`CONTRIBUTING.md`](https://github.com/fktn-k/fkYAML/blob/develop/CONTRIBUTING.md) file for information.  
+We 
+
 ## Used third-party tools
 
 The fkYAML library itself depends only on C++ standards and licensed under the MIT licence.  
 However, it is built, tested and documented with a lot of third-party tools and services.  
 Thanks a lot!  
 
-- [**Clang**](https://clang.llvm.org/) for compilation, coding style checks, and/or static/runtime analysis.
+- [**Clang**](https://clang.llvm.org/) for compilation, coding style checks, and static/runtime analysis.
 - [**CMake**](https://cmake.org/) for automation of build & testing.
 - [**Coveralls**](https://coveralls.io/) to measure [code coverage](https://coveralls.io/github/fktn-k/fkYAML?branch=develop).
 - [**Catch2**](https://github.com/catchorg/Catch2) as a unit-test framework.