diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 000000000..b776227bd --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,8 @@ +{ + "default": true, + "MD013": false, + "MD026": false, + "MD024": false, + "MD029": {"style": "ordered"}, + "MD041": false +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f4635a90..f4da98c88 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,32 +7,32 @@ please follow the workflow explained in this document. ## Table of Content -* [Prerequisites](#prerequisites) -* [Pull Requests](#pull-requests) -* [Getting started with Git workflow](#getting-started-with-git-workflow) - * [1. Clone Boost super-project](#1-clone-boost-super-project) - * [2. Checkout Boost.GIL development branch](#2-checkout-boostgil-development-branch) - * [3. Fork Boost.GIL repository on GitHub](#3-fork-boostgil-repository-on-github) - * [4. Submit a pull request](#4-submit-a-pull-request) - * [5. Update your pull request](#5-update-your-pull-request) -* [Development](#development) - * [Install dependencies](#install-dependencies) - * [Using Boost.Build](#using-boostbuild) - * [Using CMake](#using-cmake) - * [Using Faber](#using-faber) - * [Running clang-tidy](#running-clang-tidy) -* [Guidelines](#guidelines) +- [Prerequisites](#prerequisites) +- [Pull Requests](#pull-requests) +- [Getting started with Git workflow](#getting-started-with-git-workflow) + - [1. Clone Boost super-project](#1-clone-boost-super-project) + - [2. Checkout Boost.GIL development branch](#2-checkout-boostgil-development-branch) + - [3. Fork Boost.GIL repository on GitHub](#3-fork-boostgil-repository-on-github) + - [4. Submit a pull request](#4-submit-a-pull-request) + - [5. Update your pull request](#5-update-your-pull-request) +- [Development](#development) + - [Install dependencies](#install-dependencies) + - [Using Boost.Build](#using-boostbuild) + - [Using CMake](#using-cmake) + - [Using Faber](#using-faber) + - [Running clang-tidy](#running-clang-tidy) +- [Guidelines](#guidelines) ## Prerequisites -* C++11 compiler -* Build and run-time dependencies for tests and examples: +- C++11 compiler +- Build and run-time dependencies for tests and examples: - Boost.Filesystem - Boost.Test - Headers and libraries of libjpeg, libpng, libtiff, libraw for the I/O extension. -* Experience with `git` command line basics. -* Familiarity with build toolset and development environment of your choice. -* Although this document tries to present all commands with necessary options, +- Experience with `git` command line basics. +- Familiarity with build toolset and development environment of your choice. +- Although this document tries to present all commands with necessary options, it may be a good idea to skim through the [Boost Getting Started](https://www.boost.org/more/getting_started/index.html) chapters, especially if you are going to use @@ -40,48 +40,46 @@ please follow the workflow explained in this document. ## Pull Requests -* **DO** submit all major changes to code via pull requests (PRs) rather than through +- **DO** submit all major changes to code via pull requests (PRs) rather than through a direct commit. PRs will be CI-checked first, then reviewed and potentially merged by the repo maintainers after a peer review that includes at least one maintainer. Contributors with commit access may submit trivial patches or changes to the project infrastructure configuration via direct commits (CAUTION!) -* **DO NOT** mix independent, unrelated changes in one PR. +- **DO NOT** mix independent, unrelated changes in one PR. Separate unrelated fixes into separate PRs, especially if they are in different components (e.g. core headers versus extensions). Separate real product/test code changes from larger code formatting/dead code removal changes, unless the former are extensive enough to justify such refactoring, then also mention it. -* **DO** start PR subject with "WIP:" tag if you submit it as "work in progress". +- **DO** start PR subject with "WIP:" tag if you submit it as "work in progress". A PR should preferably be submitted when it is considered ready for review and subsequent merging by the contributor. Otherwise, clearly indicate it is not yet ready. The "WIP:" tag will also help maintainers to label your PR with [status/work-in-progress]. -* **DO** give PRs short-but-descriptive names (e.g. "Add test for algorithm XXX", not "Fix #1234"). -* **DO** [refer] to any relevant issues, and include the [keywords] that automatically +- **DO** give PRs short-but-descriptive names (e.g. "Add test for algorithm XXX", not "Fix #1234"). +- **DO** [refer] to any relevant issues, and include the [keywords] that automatically close issues when the PR is merged. -* **DO** [mention] any users that should know about and/or review the change. -* **DO** ensure each commit successfully builds. The entire PR must pass all tests in +- **DO** [mention] any users that should know about and/or review the change. +- **DO** ensure each commit successfully builds. The entire PR must pass all tests in the Continuous Integration (CI) system before it'll be merged. -* **DO** address PR feedback in an additional commit(s) rather than amending the existing +- **DO** address PR feedback in an additional commit(s) rather than amending the existing commits, and only rebase/squash them when necessary. This makes it easier for reviewers to track changes. -* **DO** assume that the [Squash and Merge] will be used to merge your commit unless you +- **DO** assume that the [Squash and Merge] will be used to merge your commit unless you request otherwise in the PR. -* **DO** NOT fix merge conflicts using a merge commit. Prefer git rebase. -* **DO** NOT submit changes to the original legacy tests, see +- **DO** NOT fix merge conflicts using a merge commit. Prefer git rebase. +- **DO** NOT submit changes to the original legacy tests, see [test/legacy/README.md](test/legacy/README.md). ### Merging Pull Requests (for maintainers with write access) -* **DO** use [Squash and Merge] by default for individual contributions unless requested +- **DO** use [Squash and Merge] by default for individual contributions unless requested by the PR author. Do so, even if the PR contains only one commit. It creates a simpler - history than [Create a Merge Commit].
- Reasons that PR authors may request the true merge recording a merge commit - may include (but are not limited to): - - * The change is easier to understand as a series of focused commits.
- Each commit in the series must be buildable so as not to break git bisect. - * Contributor is using an e-mail address other than the primary GitHub address - and wants that preserved in the history.
- Contributor must be willing to squash the commits manually before acceptance. + history than [Create a Merge Commit]. Reasons that PR authors may request the true + merge recording a merge commit may include (but are not limited to): + - The change is easier to understand as a series of focused commits. + Each commit in the series must be buildable so as not to break git bisect. + - Contributor is using an e-mail address other than the primary GitHub address + and wants that preserved in the history. + Contributor must be willing to squash the commits manually before acceptance. ## Getting started with Git workflow @@ -315,8 +313,8 @@ By default, Boost.GIL uses Boost.Build to build all the executables. We also provide configuration for two alternative build systems: -* [CMake](https://cmake.org) -* [Faber](http://stefan.seefeld.name/faber/) +- [CMake](https://cmake.org) +- [Faber](http://stefan.seefeld.name/faber/) **NOTE:** The CMake and Faber are optional and the corresponding build configurations for Boost.GIL do not offer equivalents for all Boost.Build features. Most important difference to recognise is that Boost.Build will @@ -394,15 +392,18 @@ The provided CMake configuration allows a couple of ways to develop Boost.GIL: 3. Using [cloned Boost super-project](#cloned-boost-super-project), inside modular `libs/gil`. This mode requires prior deployment of `boost` virtual directory with headers and stage build of required libraries, for example: - ```shell - ./b2 -j8 headers - ./b2 -j8 variant=debug --with-test --with-filesystem stage - ./b2 -j8 variant=release --with-test --with-filesystem stage - ``` - or, depending on specific requirements, more complete build: - ```shell - ./b2 -j8 variant=debug,release address-model=32,64 --layout=versioned --with-test --with-filesystem stage - ``` + + ```shell + ./b2 -j8 headers + ./b2 -j8 variant=debug --with-test --with-filesystem stage + ./b2 -j8 variant=release --with-test --with-filesystem stage + ``` + + or, depending on specific requirements, more complete build: + + ```shell + ./b2 -j8 variant=debug,release address-model=32,64 --layout=versioned --with-test --with-filesystem stage + ``` Using the installed Boost enables a lightweight mode for the library development, inside a stand-alone clone Boost.GIL repository and without any need to clone the @@ -415,21 +416,21 @@ and search for `option`. Here is an example of such lightweight workflow in Linux environment (Debian-based): -* Install required Boost libraries +- Install required Boost libraries ```shell sudo apt-get update sudo apt-get install libboost-dev libboost-test-dev libboost-filesystem-dev ``` -* Clone Boost.GIL repository +- Clone Boost.GIL repository ```shell git clone https://github.com/boostorg/gil.git cd gil ``` -* Configure build with CMake +- Configure build with CMake ```shell mkdir _build @@ -438,44 +439,42 @@ Here is an example of such lightweight workflow in Linux environment (Debian-bas ``` **TIP:** By default, tests and [examples](example/README.md) are compiled using - the minimum required C++11. - Specify `-DCMAKE_CXX_STANDARD=14|17|20` to use newer version. - For more CMake options available for GIL, check `option`-s defined - in the top-level `CMakeLists.txt`. + the minimum required C++11. + Specify `-DCMAKE_CXX_STANDARD=14|17|20` to use newer version. + For more CMake options available for GIL, check `option`-s defined + in the top-level `CMakeLists.txt`. - **TIP:** If CMake is failing to find Boost libraries, especially built with - `--layout=versioned`, you can try a few hacks: - - - `-DBoost_ARCHITECTURE=-x64` to help CMake find Boost 1.66 and above + **TIP:** If CMake is failing to find Boost libraries, especially built + with `--layout=versioned`, you can try a few hacks: + - option `-DBoost_ARCHITECTURE=-x64` to help CMake find Boost 1.66 and above add an architecture tag to the library file names in versioned build The option added in CMake 3.13.0. - - - `-DBoost_COMPILER=-gcc5` or `-DBoost_COMPILER=-vc141` to help CMake earlier + - option `-DBoost_COMPILER=-gcc5` or `-DBoost_COMPILER=-vc141` to help CMake earlier than 3.13 match your compiler with toolset used in the Boost library file names (i.e. `libboost_unit_test_framework-gcc5-mt-x64-1_69` and not `-gcc55-`). Fixed in CMake 3.13.0. + - if CMake is still failing to find Boost, you may try `-DBoost_DEBUG=ON` to + get detailed diagnostics output from `FindBoost.cmake` module. - - if CMake is still failing to find Boost, you may try `-DBoost_DEBUG=ON` to - get detailed diagnostics output from `FindBoost.cmake` module. - -* List available CMake targets +- List available CMake targets ```shell cmake --build . --target help ``` -* Build selected target with CMake +- Build selected target with CMake ```shell cmake --build . --target gil_test_pixel ``` -* List available CTest targets +- List available CTest targets ```shell ctest --show-only | grep Test ``` -* Run selected test with CTest + +- Run selected test with CTest ```shell ctest -R gil.tests.core.pixel @@ -568,29 +567,30 @@ Major refactoring overhaul is ongoing.* Maintain structure your source code files according to the following guidelines: -* Name files in meaningful way. -* Put copyright and license information in every file -* If your changes [meet a certain threshold of originality](https://www.boost.org/users/license.html), +- Name files in meaningful way. +- Put copyright and license information in every file +- If your changes [meet a certain threshold of originality](https://www.boost.org/users/license.html), add yourself to the copyright notice. Do not put any additional authorship or file comments (eg. no `\file` for Doxygen), revision information, etc. -* In header, put `#include` guard based on header path and file name +- In header, put `#include` guard based on header path and file name + ```cpp #ifndef BOOST_GIL____HPP #define BOOST_GIL____HPP ... #endif ``` -* Make sure each [header is self-contained](https://github.com/boostorg/gil/wiki/Include-Directives-Order), i.e. that they include all headers they need. -* All public headers should be placed in `boost/gil/` or `boost/gil//`. -* All non-public headers should be placed `boost/gil/detail` or `boost/gil//detail`. -* All public definitions should reside in scope of `namespace boost { namespace gil {...}}`. -* All non-public definitions should reside in scope of `namespace boost { namespace gil { namespace detail {...}}}`. -* Write your code to fit within **100** columns of text. -* Use [EditorConfig](https://editorconfig.org) for your editor and enable [.editorconfig](https://github.com/boostorg/gil/blob/develop/.editorconfig) to: - * Indent with **4 spaces** and no tabs. - * Trim any trailing whitespaces. -* Do not increases the indentation level within namespace. +- Make sure each [header is self-contained](https://github.com/boostorg/gil/wiki/Include-Directives-Order), i.e. that they include all headers they need. +- All public headers should be placed in `boost/gil/` or `boost/gil//`. +- All non-public headers should be placed `boost/gil/detail` or `boost/gil//detail`. +- All public definitions should reside in scope of `namespace boost { namespace gil {...}}`. +- All non-public definitions should reside in scope of `namespace boost { namespace gil { namespace detail {...}}}`. +- Write your code to fit within **100** columns of text. +- Use [EditorConfig](https://editorconfig.org) for your editor and enable [.editorconfig](https://github.com/boostorg/gil/blob/develop/.editorconfig) to: + - Indent with **4 spaces** and no tabs. + - Trim any trailing whitespaces. +- Do not increases the indentation level within namespace. [status/work-in-progress]: https://github.com/boostorg/gil/labels/status%2Fwork-in-progress [refer]: https://help.github.com/articles/autolinked-references-and-urls/ diff --git a/README.md b/README.md index 2d6fcc223..b47e6f5c5 100644 --- a/README.md +++ b/README.md @@ -47,8 +47,9 @@ variety of images with performance similar to hand-writing for a specific image ## Documentation -- Latest release: https://boost.org/libs/gil -- Development: http://boostorg.github.io/gil/ +- [Latest release](https://boost.org/libs/gil) +- [Branch master](http://boostorg.github.io/gil/) (latest release with minor changes) +- [Branch develop](http://boostorg.github.io/gil/develop/) See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions about how to build and run tests, examples. @@ -74,10 +75,10 @@ Optionally, in order to build and run tests and examples: The official repository contains the following branches: -* [**master**](https://github.com/boostorg/gil/tree/master) This +- [**master**](https://github.com/boostorg/gil/tree/master) This holds the most recent snapshot with code that is known to be stable. -* [**develop**](https://github.com/boostorg/gil/tree/develop) This +- [**develop**](https://github.com/boostorg/gil/tree/develop) This holds the most recent snapshot. It may contain unstable code. ## Community @@ -106,7 +107,7 @@ with solving reported issues, especially those labelled with: - [status/need-help](https://github.com/boostorg/gil/labels/status%2Fneed-help) - [status/need-feedback](https://github.com/boostorg/gil/labels/status%2Fneed-feedback) -- [need-minimal-example ](https://github.com/boostorg/gil/labels/status%2Fneed-minimal-example) +- [need-minimal-example](https://github.com/boostorg/gil/labels/status%2Fneed-minimal-example) Any feedback from users and developers, even simple questions about how things work or why they were done a certain way, carries value and can be used to improve the library.