-
-
# Contributing to Boost.GIL
Boost.GIL is a member of [Boost](https://www.boost.org) libraries.
## 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)
- * [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
-* 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,
+- 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,
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
## 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 />
- 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 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
```shell
cd libs/gil
-git remote add username https://github.com/username/gil.git
+git remote add <username> https://github.com/<username>/gil.git
+```
+
+or, if you cloned from your fork already, add the upstream as `origin` remote:
+
+```shell
+git remote add upstream https://github.com/boostorg/gil.git
+# or
+git remote rename origin <username>
+git remote add origin https://github.com/boostorg/gil.git
```
### 4. Submit a pull request
All Boost.GIL contributions should be developed inside a topic branch created by
branching off the `develop` branch of [boostorg/gil](https://github.com/boostorg/gil).
-**IMPORTANT:** Pull Requests *must* come from a branch based on `develop`, and *never* on `master`.
+**IMPORTANT:** Pull Requests *must* come from a branch based on `develop`,
+and *never* on `master`.
**NOTE:** The branching workflow model
[Boost recommends](https://svn.boost.org/trac10/wiki/StartModWorkflow)
```shell
cd libs/gil
git checkout feature/foo
-git push username feature/foo
+git push <username> feature/foo
```
Finally, sign in to your GitHub account and
### 5. Update your pull request
-In simplest (and recommended) case , your the pull request you submitted earlier
-has *a single commit*, so you can simply update the existing commit with any
-modifications required to fix failing CI builds or requested by reviewers.
+Depending on actual purpose of the update, you can follow a different
+strategy to update your pull request:
+
+- Use `git commit --amend`, `git rebase` and `git push --force` when your
+ pull request is still *work-in-progress* and not ready for review yet.
+- Use `git commit`, `git merge` and `git push` to update your pull request
+ during review, in response to requests from reviewers.
-First, it is a good idea to synchronize your topic branch with the latest
-changes in the upstream `develop` branch:
+**NOTE:** Once review of your work has started, you should not rebase your work.
+You should create new commits and update your topic branch. This helps with
+traceability in the pull request and prevents the accidental history breakage.
+Those who review your work may be fetching it into their fork for local review.
+
+#### Synchronise pull request branch
+
+Keep your topic branch up to date and synchronized with the upstream `develop` branch:
```shell
cd libs/gil
git checkout develop
git pull origin develop
git checkout feature/foo
+```
+
+If review of your work has not started, *prefer* to merge:
+
+```shell
+git merge develop
+git push <username> feature/foo
+```
+
+If your PR is still *work-in-progress*, you may rebase if you like:
+
+```shell
git rebase develop
+git push --force <username> feature/foo
```
-Next, make your edits.
+#### Amend last commit of pull request
-Finally, `git commit --amend` the *single-commit* in your topic branch and
-update the pull request:
+If your pull request is a *work-in-progress* and has not been reviewed yet,
+you may amend your commit or rebase onto the `develop` branch:
```shell
cd libs/gil
git checkout feature/foo
git add -A
git commit --amend
-git push --force username feature/foo
+git push --force <username> feature/foo
```
-**WARNING:** Ensure your pull request has a single commit, otherwise the
-force push can corrupt your pull request.
+#### Add new commits to pull request
-If you wish to update pull request adding a new commit, then create new
-commit and issue regular push:
+In order to update your pull request, for example in response to a change
+request from reviewer, just add new commits:
```shell
-git commit -m "Fix variable name"
-git push username feature/foo
+cd libs/gil
+git checkout feature/foo
+git add -A
+git commit -m "Fix build Travis CI failures"
+git push <username> feature/foo
```
## Development
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
automatically build any other Boost libraries required by Boost.GIL as dependencies.
+### Install dependencies
+
+Boost.GIL tests and examples use the GIL I/O extension which depends on
+third-party libraries for read and write support of specific image formats:
+
+```shell
+sudo apt-get install libjpeg-dev libpng-dev libtiff5-dev libraw-dev
+```
+
### Using Boost.Build
The [b2 invocation](https://boostorg.github.io/build/manual/develop/index.html#bbv2.overview.invocation)
```shell
cd libs/gil
-../../b2 -j8 test
+../../b2 -j8 test/core
```
Run all tests for selected extension (from Boost root directory, as alternative):
```shell
-./b2 -j8 libs/gil/io/test
-./b2 -j8 libs/gil/numeric/test
-./b2 -j8 libs/gil/toolbox/test
+./b2 -j8 libs/gil/test/io
+./b2 -j8 libs/gil/test/numeric
+./b2 -j8 libs/gil/test/toolbox
```
Run I/O extension tests bundled in target called `simple`:
```shell
-./b2 libs/gil/io/test//simple
+./b2 libs/gil/test/io//simple
```
-*TODO:* _Explain I/O dependencies (libjpeg, etc.)_
-
### Using CMake
Maintainer: [@mloskot](https://github.com/mloskot)
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
whole Boost super-project.
+**TIP:** For the lightweight setup, prefer latest release of Boost.
+
For available custom CMake options, open the top-level `CMakeLists.txt`
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
```
-* Optionally, install libraries required by the I/O extension
-
- ```shell
- sudo apt-get update
- sudo apt install libtiff-dev libpng-dev libjpeg-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
```
**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`.
-
- **TIP:** If CMake is failing to find Boost libraries, especially built with
- `--layout=versioned`, you can try a few hacks:
-
- - `-DGIL_DOWNLOAD_FINDBOOST=ON` to use very latest version of
- `FindBoost.cmake` without upgrading your CMake installation.
-
- - `-DBoost_ARCHITECTURE=-x64` to help CMake find Boost 1.66 and above
+ 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:
+ - 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
```
+#### CMake configuration for Visual Studio
+
+We provide [example/cmake/CMakeSettings.json](https://github.com/boostorg/gil/blob/develop/example/cmake/CMakeSettings.json)
+with reasonable default settings for the [CMake support in Visual Studio](https://go.microsoft.com//fwlink//?linkid=834763).
+See [example/cmake/README.md](example/cmake/README.md) for more details.
+
+#### CMake configuration for Visual Studio Code
+
+We provide [example/cmake/cmake-variants.yaml](https://github.com/boostorg/gil/blob/develop/example/cmake/cmake-variants.yaml)
+with reasonable default settings for the [CMake Tools](https://github.com/vector-of-bool/vscode-cmake-tools) extension.
+See [example/cmake/README.md](example/cmake/README.md) for more details.
+
### Using Faber
Maintainer: [@stefanseefeld](https://github.com/stefanseefeld)
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 **90** columns of text (see discussion on [preferred line length](https://lists.boost.org/boost-gil/2018/04/0028.php) in GIL).
-* 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/
projects / platform / upstream / boost.git / blobdiff