Skip to content

Guidelines for Contributors

Jump to bottom Edit New page
Cem Bassoy edited this page Feb 10, 2022 · 9 revisions

uBlas is a free and open-source library that is part of the Boost C++ libraries. We welcome anyone who wants to contribute and enhance uBlas by for instance adding new features, fixing software bugs or enhance our software and infrastructure in general.

Table of Content

Prerequisites

Contributing to Boost.uBlas can be quite challenging which is why it is very important to first read and make yourself acquainted with Boost.uBlas. We assume that you

  • you are an experienced C++ programmer who can apply many of the C++17 and C++20 features
  • are able to apply and understand most of the C++ core guidelines
  • have experience with git and understand collaborative workflows
  • communicate and engage with everyone in the community to behave as describe in our code of conduct
  • you will read this document until the end

We encourage you to

If you have never used Boost.uBlas, you should

  • clone and install Boost.uBlas according to the installation documentation
  • build and play around with already existing examples
  • build and execute tests

Make sure you understand how Boost.uBlas contributors communicate:

  • software versioning and feature creation happens in the code and pull requests tabs
  • existing and future projects are placed inside projects tab
  • issues and bugs are placed inside the issues tab
  • discussions, questions, proposals, etc. usually happen in the discussions tab
  • announcements and short questions are placed and raised in the gitter channel

Git Workflow

Among many existing workflows, we have decided to mainly work according to the gitflow. It is based on the Feature Branch Workflow in which all feature development takes place in dedicated branches instead of the main or master branch. We have decided against a trunk-based development as most of the new features contain many additions and deletions which makes it hard to commit piecewise without breaking the trunk branch. The workflow might change in future when most of the features or contributions contain minor additions.

Boostorg/ublas consists of at least the master and develop branch. The master branch stores the official release history, and the develop branch serves as an integration branch for features. Features should be named feature/<feature-name>, while bug fixes should be named bugfix/<bugfix-name>. A release branch does not exist. This encapsulation makes it easy for multiple developers to work on a particular feature without disturbing the main codebase on master. Minor adjustments are allowed on develop when those changes do not interfere with the flow of other contributors. Merging features and bug fixes into develop is performed with a pull-request.

If you do not have write-access you can create a fork of boostorg/ublas from which you can request pulls.

Git Commits

We want our git commit messages to be human and machine readable as described in conventional commits and angular commit message guidelines.

Commit Message Format Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

():

The header is mandatory and the scope of the header is optional. Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Pull Requests

  • 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. 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". 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. "Adding test for algorithm xyz", 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 the Continuous Integration (CI) system before it'll be merged.
  • 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 request otherwise in the PR.
  • DO NOT fix merge conflicts using a merge commit. Prefer git rebase.

Merging Pull Requests (for maintainers with write access)

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

Getting started with Git workflow

First, you need learn some minimal basics of the modular Boost super-project workflow.

The following steps are based on the official Boost Getting Started.

NOTE: For brevity, commands below use notation for POSIX-like operating systems and you may need to tweak them for Windows systems.

1. Clone Boost super-project

The preparation involves the following steps:

  1. Clone the Boost super-project
git clone --recursive --jobs 8 https://github.com/boostorg/boost.git
  1. Switch the Boost super-project to desired branch, master or develop 
cd boost
git checkout master

TIP: Modular Boost Library Maintenance guide, for more realistic test environment, recommends to develop and test individual Boost library against other Boost libraries as defined by the Boost super-project master branch:

cd boost
git checkout master
git pull
git submodule update --init --recursive --jobs 8
  1. Build the b2 driver program for Boost.Build engine.
./bootstrap.sh
./b2 --version

TIP: For more convenient path-less invocation, you can copy the b2 program to a location in your PATH.

  1. Optionally, create full content of /boost virtual directory with all Boost headers linked from the individual modular Boost libraries. If you skip this step, executing b2 to run tests will automatically create the directory with all headers required by Boost.uBLAS and tests.
./b2 -j8 headers

TIP: If something goes wrong, you end up with incomplete or accidentally modified files in your clone of the super-project repository, or you simply wish to start fresh, then you can clean and reset the whole repository and its modules:

git clean -xfd
git submodule foreach --recursive git clean -xfd
git reset --hard
git submodule foreach --recursive git reset --hard
git submodule update --init --recursive --jobs 8

2. Checkout Boost.uBLAS development branch

Regardless if you decide to develop again master (recommended) or develop branch of the Boost super-project, you should always base your contributions (i.e. topic branches) on Boost.uBLAS develop branch.

  1. Go to the Boost.uBLAS library submodule.
cd libs/numeric/ublas/test
  1. Checkout the develop branch and bring it up to date
git checkout develop
git branch -vv
git pull origin develop

3. Fork Boost.uBLAS repository on GitHub

Follow Forking Projects guide to get personal copy of boostorg/ublas repository from where you will be able to submit new contributions as pull requests.

Add your fork as git remote to the Boost.uBLAS submodule:

cd libs/numeric/ublas
git remote add fork https://github.com/somename/ublas.git
git fetch fork

4. Submit a pull request

All Boost.uBLAS contributions should be developed inside a topic branch created by branching off the develop branch of boostorg/ublas.

IMPORTANT: Pull Requests must come from a branch based on develop, and never on master.

NOTE: The branching workflow model Boost recommends is called Git Flow.

For example:

cd libs/numeric/ublas
git checkout develop
git checkout -B feature --track fork/develop

Now, you are set to to develop a new feature for Boost.uBLAS, then git add and git commit your changes.

Once it's finished, you can submit it as pull request for review:

cd libs/numeric/ublas
git checkout feature
git push

Finally, sign in to your GitHub account and create a pull request.

Your pull request will be automatically built and tests will run on Travis CI and AppVeyor (see README for builds status). Please, keep an eye on those CI builds and correct any problems detected in your contribution by updating your pull request.

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.

First, it is a good idea to synchronize your topic branch with the latest changes in the upstream develop branch:

cd libs/numeric/ublas
git checkout develop
git pull origin develop
git checkout feature
git rebase develop

Next, make your edits.

Finally, git commit --amend the single-commit in your topic branch and update the pull request:

cd libs/numeric/ublas
git checkout feature
git add -A
git commit --amend
git push --force

WARNING: Ensure your pull request has a single commit, otherwise the force push can corrupt your pull request.

If you wish to update pull request adding a new commit, then create new commit and issue regular push:

git checkout feature
git commit -m "Fix variable name"
git push feature

Development

Boost.uBLAS is a header-only library which does not require sources compilation. Only test runners and example programs have to be compiled.

By default, Boost.uBLAS uses Boost.Build to build all the executables.

Using Boost.Build

The b2 invocation explains available options like toolset, variant and others.

Simply, just execute b2 to run all tests built using default variant=debug and default toolset determined for your development environment.

TIP: Pass b2 option -d 2 to output complete action text and commands, as they are executed. It is useful to inspect compilation flags.

If no target or directory is specified, everything in the current directory is built. For example, all Boost.uBLAS tests can be built and run using:

cd libs/numeric/ublas
../../../b2 -j8 release toolset=clang cxxflags="-O3" [examples/tensor/][test/tensor][...]

Run core tests only specifying location of directory with tests:

cd libs/numeric/ublas
../../../b2 -j8 toolset=clang cxxflags="-O3" test

Running clang-tidy

clang-tidy can be run on demand to diagnose or diagnose and fix or refactor source code issues.

Guidelines

Boost.uBLAS is a more than a decade old library maintained by several developers with help from a couple of dozens contributors. It is important to maintain consistent design, look and feel. Thus, below a few basic guidelines are listed.

First and foremost, make sure you are familiar with the official Boost Library Requirements and Guidelines.

Second, strive for writing idiomatic C++11, clean and elegant code.

NOTE: The Boost.uBLAS source code does not necessary represent clean and elegant code to look up to. The library has recently entered the transition to C++11. 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, 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
#ifndef BOOST_UBLAS_<DIR1>_<DIR2>_<FILE>_HPP
#define BOOST_UBLAS_<DIR1>_<DIR2>_<FILE>_HPP
...
#endif
  • Make sure each header is self-contained, i.e. that they include all headers they need.
  • All public headers should be placed in boost/numeric/ublas/ or boost/numeric/ublas/<component>/.
  • All non-public headers should be placed boost/numeric/ublas/detail or boost/numeric/ublas/component>/detail.
  • All public definitions should reside in scope of namespace boost { namespace numeric { namespace ublas {...}}}.
  • All non-public definitions should reside in scope of namespace boost { namespace numeric { namespace ublas { namespace detail {...}}}}.
  • Do not increases the indentation level within namespace.
Add a custom footer
Add a custom sidebar
Clone this wiki locally