boost/gil
2
0
Fork 0
mirror of https://github.com/boostorg/gil.git synced 2026-01-19 04:12:11 +00:00
Code Issues Projects Releases Wiki Activity

Add Markdown linting with Node package markdownlint [ci skip]

Browse Source
This commit is contained in:
Mateusz Łoskot
2019-11-04 23:54:09 +01:00
parent cb5b2e0ece
commit 9f5f24affd
3 changed files with 100 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
.markdownlint.json Normal file
View File

@@ -0,0 +1,8 @@
{
"default": true,
"MD013": false,
"MD026": false,
"MD024": false,
"MD029": {"style": "ordered"},
"MD041": false
}

138
CONTRIBUTING.md
View File

@@ -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,47 +40,45 @@ 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].<br />
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.<br />
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.<br />
- 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,12 +392,15 @@ 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
```
@@ -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
@@ -443,39 +444,37 @@ Here is an example of such lightweight workflow in Linux environment (Debian-bas
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.
* 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_<DIR1>_<DIR2>_<FILE>_HPP
#define BOOST_GIL_<DIR1>_<DIR2>_<FILE>_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/<component>/`.
* All non-public headers should be placed `boost/gil/detail` or `boost/gil/<component>/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/<component>/`.
- All non-public headers should be placed `boost/gil/detail` or `boost/gil/<component>/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/

11
README.md
View File

@@ -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.